ctxio 0.1.1

Local-first context handoff between coding agents (Claude, Codex, ChatGPT). Resume in a new agent for ~500 tokens instead of 20k.

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.

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 v0.1.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

$ 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:

$ 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:

$ 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

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

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.

Cross-agent sync (non-MCP tools)

```console $ ctx sync Created AGENTS.md Created CLAUDE.md ```

SessionStart/PreCompact hooks only help if you're in Claude Code. Most other tools — Cursor, Codex, Aider, Devin, Copilot, Gemini CLI, Windsurf — don't speak MCP, but nearly all of them do read AGENTS.md, the Linux Foundation-stewarded open standard for giving coding agents project context. ctx sync inserts one short, idempotent block into AGENTS.md and CLAUDE.md pointing at the live handoff — it does not dump the whole dynamic snapshot into them. Those files are meant to be stable, curated project context, not something that churns on every commit; .context-io/context.current.md is the one meant to change constantly. Creates either file if missing, and leaves any existing content in them completely untouched.

Agent integration (MCP)

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

pip install -e .
pytest

License

MIT