Metadata-Version: 2.4
Name: ctxio
Version: 0.1.0
Summary: Local-first context handoff between coding agents (Claude, Codex, ChatGPT). Resume in a new agent for ~500 tokens instead of 20k.
Author: Abhishek Bevinkatti
License-Expression: MIT
Project-URL: Homepage, https://github.com/bevinkatti/context-io
Project-URL: Repository, https://github.com/bevinkatti/context-io
Project-URL: Issues, https://github.com/bevinkatti/context-io/issues
Keywords: ai-agents,claude,claude-code,codex,context,mcp,developer-tools,tokens,limit-usage
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Dynamic: license-file

# Context-io

**Resume any coding session in a new AI agent for under 500 tokens — not the 20,000+ you'd burn replaying full history.**

[![CI](https://github.com/bevinkatti/context-io/actions/workflows/ci.yml/badge.svg)](https://github.com/bevinkatti/context-io/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/ctxio.svg)](https://pypi.org/project/ctxio/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

You already know this problem: you switch from Claude Code to Codex, or your
session hits auto-compact, and the agent suddenly has no idea what you were
doing. So you paste in three paragraphs of "here's what we've built so far,"
burn a few thousand tokens re-explaining it, and hope the summary is accurate.

Context-io writes your session's context to plain Markdown as you work, then
hands a new agent a **capped, ≤500-token snapshot** instead of your full
history — no LLM calls involved in generating it, just git and a few rules.
And as of v1.0, you don't even need to remember to trigger it: commits and
Claude Code's own session lifecycle do it for you.

## See it for yourself

```console
$ ctx save "set up FastAPI project skeleton" -d "routers/, models/, main.py"
Saved: set up FastAPI project skeleton

$ ctx save "added JWT auth middleware" -d "using python-jose, refresh token rotation"
Saved: added JWT auth middleware

$ ctx checkpoint "auth flow working end to end" --next "add rate limiting, write integration tests"
Checkpoint: auth flow working end to end

$ ctx handoff
── Context-io receipt ──────────────────
Handoff frame:  96 tokens (cap: 500)
Full log:       161 tokens
Savings:        40.4%
────────────────────────────────────────
Written to .context-io/context.current.md
```

That's a real run, not a mockup — and an early one. In a 500-entry stress
test, the full log grew to ~143,000 tokens while the handoff frame stayed at
40 tokens: a 99.97% reduction, still comfortably under the cap. The longer
the session, the better this gets.

## Zero-effort capture 

**A git hook that needs no agent at all:**

```console
$ ctx hooks install
Installed git post-commit hook -> .git/hooks/post-commit
Every commit now lands in the session log automatically.

$ git commit -m "fix refresh-token bug"
[main 4f2a1c9] fix refresh-token bug
# ^ that commit alone just wrote an entry to .context-io/session.full.md
```

**Claude Code hooks that remove the manual paste:**

```console
$ ctx claude-hooks --install
Wrote Claude Code hooks -> .claude/settings.local.json
SessionStart now auto-loads the handoff; PreCompact auto-checkpoints before compaction.
```

`SessionStart` means a brand-new session already has the handoff before you
type anything. `PreCompact` means a checkpoint gets written the moment
*before* Claude Code's own compaction would otherwise erase detail. Both
commands merge into whatever hooks already exist — safe to run more than
once, and won't touch other tools you have installed.

## How it works

Three plain Markdown files, all under `.context-io/`:

| File | What's in it | Size |
|---|---|---|
| `session.full.md` | Every save/checkpoint, append-only | Unbounded |
| `session.checkpoints.md` | Milestones + "what's next" | Small |
| `context.current.md` | The handoff snapshot | **≤500 tokens, enforced** |

Extraction is rule-based: git branch, diff, uncommitted files, file tree —
never an LLM call. `session.full.md` and `session.checkpoints.md` are meant
to be committed; they're project memory your teammates can read too, not
just scratch output for an agent. `context.current.md` is regenerated every
time, so `ctx init` gitignores it automatically — nobody has to figure that
out by trial and error.

## Install

```bash
pip install ctxio
```

Python 3.10+. Zero runtime dependencies — clipboard support and the hooks
above shell out to tools already on your system instead of adding new ones.

## CLI

```bash
ctx save "<summary>" -d "<detail>"       # append to the session log
ctx checkpoint "<summary>" --next "…"    # record a milestone
ctx handoff [--copy] [--cap N]           # build the capped snapshot
ctx status                               # token counts for all three files
ctx hooks install                        # git auto-capture on every commit
ctx claude-hooks --install [--shared]    # Claude Code SessionStart + PreCompact
ctx doctor                               # is everything actually wired up?
```

No `ctx init` required — the first `save` / `checkpoint` / `handoff`
initializes everything for you.

## Agent integration (MCP)

```bash
python -m ctxio.mcp_server
```

Exposes `ctx_save`, `ctx_checkpoint`, `ctx_handoff`, `ctx_status`, and
`ctx_install_hooks` over stdio — the last one means you can just tell your
agent "set up automatic checkpointing" and it wires up both hooks above by
itself. See `examples/` for ready-to-paste Claude Code and Claude Desktop
config.

## When this isn't the right tool

If what you need is resuming a session by parsing that *same* tool's own
transcript format across a dozen different agents, that's a different, and
already fairly well-served, problem. Context-io doesn't try to compete on
cross-tool format breadth. It's for people who want project memory that's
plain text, git-native, human-readable, and works with *any* MCP-capable
agent without needing to know that agent's private storage format at all.

## Contributing

Issues and PRs welcome. The whole thing is a few hundred lines of
stdlib-only Python, one file per concern:

- `ctxio/extract.py` — git-derived context
- `ctxio/budget.py` — token estimation + the hard cap
- `ctxio/store.py` — the three-file store
- `ctxio/hooks.py` — automatic capture (git + Claude Code)
- `ctxio/cli.py` / `ctxio/mcp_server.py` — the two interfaces, one code path

```bash
pip install -e .
pytest
```

## License

MIT
