Show HN: Continuum – switch AI coding agents without re-explaining your project

Developer AnasNafees1802 released Continuum v2.0.0, an open-source tool that lets users switch between AI coding agents such as Codex, Claude, and Windsurf without re-explaining their project by storing a structured memory ledger inside the project at .aicontext/. The tool installs globally via a bootstrap script and teaches each agent a protocol to read and update the memory, preserving context across sessions and agents.

Cross-agent session continuity for AI coding agents. Website https://anasnafees1802.github.io/continuum/ · Install install · v2.0.0 https://github.com/AnasNafees1802/continuum/releases/tag/v2.0.0 · MIT /AnasNafees1802/continuum/blob/main/LICENSE Switch from Codex to Claude to Antigravity — or come back tomorrow after hitting a usage limit — and your agent already knows what you're building, where you are, and what's next. No re-explaining. You're building with one AI coding agent. You ship a couple of features, then the daily limit hits and it stops. You switch to another agent — but it knows nothing . You burn time and tokens re-explaining the project, and you lose the thread of why things were done a certain way. Each agent keeps its own private history Claude Code in ~/.claude/projects/ , others elsewhere , and none of them share. The context is trapped in a silo. Continuum puts a small, structured memory ledger inside your project at .aicontext/ , and teaches every agent the same simple protocol: Read it when you start. Update it before you stop. Because the memory lives in the repo — not in any one agent's silo — context survives the switch. Any agent, any day, picks up exactly where the last one left off. your-project/ ├── .aicontext/ 📦 the portable memory gitignored, machine-local │ ├── STATE.md ⭐ where we are right now — read this first │ ├── TASKS.md in progress / backlog / done │ ├── DECISIONS.md append-only: why we chose what we chose │ ├── JOURNAL.md append-only: per-session handoff log │ ├── manifest.json metadata last agent, session count, … │ └── PROTOCOL.md the full spec agents follow ├── CLAUDE.md auto-loaded by each agent; carries the ├── AGENTS.md "read/update .aicontext/" instruction block ├── .windsurfrules Codex/Antigravity/Windsurf/Gemini read AGENTS.md ├── .claude/ │ ├── settings.local.json ⚙️ Claude Code hooks machine-local, gitignored │ └── skills/continuum/ │ ├── SKILL.md full protocol as a Claude Code skill │ └── bin/ the continuum helper CLI .ps1 + .sh Claude Code — via CLAUDE.md + the continuum skill. Codex, Antigravity, Windsurf, Gemini CLI, Cursor, Zed, … — via, the AGENTS.md emerging cross-agent standard https://agents.md read by 60k+ projects. Windsurf — also gets a native .windsurfrules for belt-and-suspenders coverage. Any agent that reads one of those files participates automatically. Installs Continuum into every AI agent on your machine, once — applies to all your projects: Windows / PowerShell irm https://raw.githubusercontent.com/AnasNafees1802/continuum/main/bootstrap.ps1 | iex macOS / Linux curl -fsSL https://raw.githubusercontent.com/AnasNafees1802/continuum/main/bootstrap.sh | bash That downloads the repo to a temp folder, runs the global installer, and cleans up. Variations: | Goal | Windows | macOS / Linux | |---|---|---| Force all known agents | $env:CONTINUUM ALL='1'; irm …/bootstrap.ps1 | iex | curl -fsSL …/bootstrap.sh | CONTINUUM ALL=1 bash | Per-project ledger in current dir | $env:CONTINUUM MODE='project'; irm …/bootstrap.ps1 | iex | curl -fsSL …/bootstrap.sh | CONTINUUM MODE=project bash | Piping a script from the internet to your shell runs remote code. That's standard for installers, but you should trust the source — read / bootstrap.ps1 first if you like. Prefer not to pipe? Use the clone method below. bootstrap.sh git clone https://github.com/AnasNafees1802/continuum.git cd continuum Wires the Continuum protocol into each agent's global config so every project you open in any agent follows it automatically when that project has a .aicontext/ folder . Run it once from the cloned folder: Windows / PowerShell -ExecutionPolicy Bypass avoids the unsigned-script block powershell -ExecutionPolicy Bypass -File .\install-global.ps1 detected agents only powershell -ExecutionPolicy Bypass -File .\install-global.ps1 -All force all known agents macOS / Linux bash ./install-global.sh detected agents only ALL=1 bash ./install-global.sh force all known agents It installs the shared helper once to ~/.continuum/bin/ , then for each agent it detects writes the protocol into that agent's global instruction file and wires its native hooks: | Agent | Global instruction file | Hooks wired into | |---|---|---| | Claude Code | ~/.claude/CLAUDE.md + skill ~/.claude/skills/continuum/ | ~/.claude/settings.json | | Codex | ~/.codex/AGENTS.md | ~/.codex/hooks.json | | Gemini CLI | ~/.gemini/GEMINI.md | ~/.gemini/settings.json | | Antigravity | ~/.gemini/AGENTS.md cross-tool; avoids the GEMINI.md conflict | — | | Cursor | User Rules / AGENTS.md in-repo | ~/.cursor/hooks.json | | Windsurf | ~/.codeium/windsurf/memories/global rules.md | ~/.codeium/windsurf/hooks.json | Hook merges are idempotent and preserve any hooks you already have. After this, the only per-project step is creating the .aicontext/ ledger — which any agent will do for you on request Claude self-bootstraps; or run Option B . Run from the cloned folder, pointing at the project you want continuity for: Windows / PowerShell powershell -ExecutionPolicy Bypass -File .\install.ps1 -Target C:\path\to\my-project macOS / Linux bash ./install.sh /path/to/my-project This creates .aicontext/ and drops CLAUDE.md / AGENTS.md / .windsurfrules adapters in the repo root. Useful when you haven't done the global install, or want the adapters committed for teammates. All installers are idempotent— re-run any time to refresh without touching accumulated context. The per-project installer takes -Force PS / FORCE=1 sh to also reset the ledger. A memory ledger is only as good as the discipline that keeps it current. The naïve version — "agent, please read this at start and update it before you stop" — breaks in exactly the case Continuum exists for: when a usage limit or crash kills the session, there's no chance to write the handoff. So Continuum doesn't rely on remembering. It wires native hooks into every agent that has them and uses a shared helper CLI for the bookkeeping: Guaranteed catch-up — a session-start hook injects STATE.md plus recent journal + drift notes into context every session. Catching up stops being something the agent might forget. Handoff before context loss — a pre-compaction hook fires right as the context window is about to compact and prompts the handoff then , while the detail still exists. A gentle safety net, not a nag — a stop hook reminds you once per session if you changed files but never saved, or if you committed code but never recorded the decision behind it. Once, never twice. Keeps TASKS.md / DECISIONS.md honest too — not just STATE.md . Reconstruction for hard kills — if a session ends with no handoff limit/crash , the next session detects the gap and continuum import --from auto rebuilds a draft handoff from the last agent's own transcript plus a git-based view. The one moment a hook can't capture is recovered after the fact — even across a tool switch Codex → Claude, or back . Never trust a stale ledger — catch-up compares the saved git commit to HEAD and flags drift "12 commits + uncommitted changes since last save" , so the agent verifies against git instead of confidently briefing you from an out-of-date snapshot. Bounded cost — continuum save rotates old JOURNAL.md entries into .aicontext/archive/ , so the ledger never bloats the context it's meant to save. The helper is plain PowerShell + bash no runtime, no dependencies . It only does mechanics — timestamps, manifest.json , git checks, transcript parsing, rotation. The agent still writes the actual prose ; that judgment isn't something to automate away. | Agent | Catch-up start | Handoff prompt | Stop nudge | Transcript recon | Status | |---|---|---|---|---|---| | Claude Code | ✅ SessionStart hook | ✅ PreCompact | ✅ Stop | ✅ native | ✅ verified | | Codex | ✅ SessionStart hook | ✅ PreCompact | ✅ Stop | ✅ native cwd-matched | ✅ verified | | Antigravity | ✅ honor-protocol¹ | — | — | git-based² | ✅ verified | | Gemini CLI | ✅ SessionStart hook | ✅ PreCompress | — | ✅ native | 🧪 beta | | Cursor | ✅ sessionStart hook | ✅ preCompact | ✅ stop | git-based | 🧪 beta | | Windsurf | ✅ first per-turn hook | — | — | git-based | 🧪 untested | Status = has it been confirmed on a real session? ✅ verified · 🧪 not yet. ¹ Antigravity has no hook system, so catch-up rides the honor-protocol it reads AGENTS.md / GEMINI.md and can run the continuum CLI itself . ² Its transcripts are binary, so reconstruction uses the git floor. Universal floor:even where native hooks or transcript parsing aren't available, thegit-based reconstruction --from git , always included in auto rebuilds "what changed" from git log / git diff , and the honor-protocol in each agent's instruction file AGENTS.md / GEMINI.md / CLAUDE.md / rules still drives read-at-start, save-before-stop. Continuity never fully fails, on any tool. Verified end-to-end on real Claude Code, Codex, and Antigravity sessions; Gemini/Cursor rely on the same mechanisms and the floor, pending a real-session pass. Day 1, Codex: you build a feature. Before the limit hits, Codex updates STATE.md and appends a JOURNAL.md entry: "Built auth flow, left off at wiring the token refresh." Day 1, later, Claude Code: you open the project. Claude reads .aicontext/STATE.md , says "📍 Caught up: building the auth flow, next is token refresh," and continues — no re-explaining. Day 2, Antigravity: same thing. Everyone shares one brain. Gitignored by default — .aicontext/ is machine-local, not pushed. The adapter files are committed, so the protocol travels with the repo and each clone re-inits its own local ledger. Want it shared with your team? Remove .aicontext/ from .gitignore and commit it. Plain Markdown + JSON — no runtime, no service, no lock-in. Readable and editable by hand.— so you always have both a fast current snapshot and a full, trustworthy history. STATE.md is living; JOURNAL.md / DECISIONS.md are append-only - ✅ ~~Deterministic capture~~— shipped: native session-start / pre-compaction / stop hooks on Claude Code, Codex, Gemini and Cursor Windsurf via its per-turn hook . - ✅ ~~History importer~~— shipped: continuum import --from auto reconstructs a missed handoff from the last agent's transcript Claude/Codex/Gemini native parsers plus a universal git-based view. - ✅ ~~Drift detection~~— shipped: catch-up flags commits/changes since the ledger was last saved. - ✅ ~~One-line remote install~~— shipped see One line, no clone -one-line-no-clone-recommended . Native transcript parsers for Cursor/Windsurf SQLite state.vscdb — today they use git-based reconstruction. Team mode — optional shared committed ledger with conflict-resistant per-session journal files. Built by Anas Nafees . Continuum is open source and contributions are welcome — open an issue or PR at github.com/AnasNafees1802/continuum https://github.com/AnasNafees1802/continuum . If it saves you from re-explaining your project to yet another agent, a ⭐ is appreciated. MIT /AnasNafees1802/continuum/blob/main/LICENSE © Anas Nafees — free to use, modify, and distribute. Use it everywhere.