Your coding agent forgets everything the moment its window closes. CarryCtx doesn't.
You close Claude Code. Tomorrow's session — or a teammate's, or a different agent entirely — has no idea what you were doing, what's done, what's blocked, or what branch you were on. Chat history isn't project state. Commit messages don't explain intent. Markdown notes go stale the moment you stop updating them by hand.
CarryCtx is a local-first CLI that gives coding agents a real memory: structured tasks, progress, decisions, and Git-aware checkpoints, all persisted in a single SQLite file inside your repo. Any agent, in any window, on any worktree, runs one command and picks up exactly where the last one left off.
carryctx resumeTask CTX-0014 — Add streaming CSV export
Owner: claude-core · Status: in_progress
Last checkpoint (12m ago):
Done: Implemented CSV writer, added unit tests
Remaining: Add streaming support for >1M rows
Blocker: None
Git: branch feature/csv-export, HEAD 32ac891, 2 files dirty
Next: Wire the writer into the streaming pipeline
No re-reading chat logs. No "catch me up" prompts. No stale hand-off doc.
English | 简体中文
cargo install carryctxnpm install -g carryctx
# or
bun add -g carryctxDownload the prebuilt binary for your platform from the releases page.
brew tap Xuepoo/tap https://github.com/Xuepoo/homebrew-tap.git
brew install carryctxscoop bucket add Xuepoo https://github.com/Xuepoo/scoop-bucket.git
scoop install carryctxyay/paru -S carryctx
yay/paru -S carryctx-bincd your-project
carryctx init
carryctx agent register --name my-agent --provider claude-code
carryctx task create --title "My first task"
carryctx task claim CTX-0001
carryctx session start
carryctx resume| Markdown hand-off doc | Chat history | CarryCtx | |
|---|---|---|---|
| Survives a closed window | Only if someone remembers to write it | No | Yes |
| Machine-queryable | No — free text | No | Yes — SQL + --json |
| Tracks Git state automatically | No | No | Yes (branch, HEAD, dirty files, diff stats) |
| Works across different agents | Depends on convention | No — tied to one tool's context | Yes — agent-agnostic |
| Detects stale state | No | No | Yes (carryctx doctor) |
| Leaves your machine | No | Depends on provider | Never — 100% local |
CarryCtx doesn't replace Git and it doesn't run your agent. It's the layer in between: Git owns code history, CarryCtx owns why the code is the way it is right now.
| Command | What it gives you |
|---|---|
task, progress, depend |
Structured work units with dependencies, blockers, and micro-progress logs — not a prose to-do list |
checkpoint, resume, context |
Git-aware state snapshots and LLM-ready context dumps |
session, agent, handoff |
Multi-agent, multi-window collaboration with explicit ownership hand-off |
worktree |
Isolated parallel work per task, auto-bound to the right branch |
graph |
AST-scanned code dependency graph, exportable as Mermaid/DOT/ASCII |
search |
SQLite FTS5 search across tasks, progress, checkpoints, and decisions, with owning task, branch, and highlighted snippets |
mcp |
A stdio Model Context Protocol server — plug straight into Cursor, Claude Desktop, and other MCP clients |
stats |
Agent performance analytics — session length, throughput, exportable as Markdown/CSV |
hooks |
Git post-commit auto-checkpointing, task-ID-prefixed commit messages |
doctor |
Self-diagnosis for orphaned tasks, missing hooks, and DB drift |
sync |
Push/pull state across machines when you need it — network access stays opt-in, never default |
Find prior work by content without remembering which task or branch contained it:
carryctx search "markdown worker protocol"
carryctx search aria-owns --type decision --json
carryctx search "auth flow" --status in_progress --owner claude-codeResults are ranked by relevance and resolve every hit back to its owning task, status, and best-known branch. Queries support exact phrases, uppercase AND/OR/NOT, and trailing * prefix matches. Bare hyphenated terms such as aria-owns, pointer-events, and --deny-warnings are treated as literal text.
Enable tab-completion for all commands and flags:
# Bash
carryctx completions bash >> ~/.bash_completion.d/carryctx
# Zsh (add to ~/.zshrc)
eval "$(carryctx completions zsh)"
# Fish
carryctx completions fish > ~/.config/fish/completions/carryctx.fish
# PowerShell
carryctx completions powershell | Out-String | Invoke-ExpressionInstall CarryCtx git hooks to auto-checkpoint on commit and prefix commit messages with the active task ID:
carryctx hooks install # install post-commit + prepare-commit-msg hooks
carryctx hooks status # check which hooks are active
carryctx hooks uninstall # remove CarryCtx hooks (restores .bak if present)carryctx doctor # check project health (git, db, hooks, orphaned tasks)
carryctx doctor --json # machine-readable outputLoad the CarryCtx skills to give your coding agent first-class CarryCtx awareness. All skills ship from carryctx-skills via the Vercel Labs Skills CLI.
List available skills:
npx skills add Xuepoo/carryctx-skills --listInstall all skills for all detected agents:
npx skills add Xuepoo/carryctx-skills --allInstall selected skills for specific agents:
npx skills add Xuepoo/carryctx-skills \
--skill carryctx-core \
--skill carryctx-rules \
--skill carryctx-workflows \
--skill carryctx-personas \
--skill carryctx-handoff \
--agent codex \
--agent claude-code \
--agent cursor \
--agent github-copilotUse one skill without installing it:
npx skills use Xuepoo/carryctx-skills --skill carryctx-coreThe skills teach agents to manage sessions, tasks, progress, and checkpoints through CarryCtx — enabling persistent context across agent restarts and worktree switches.
- Full docs & guides: carryctx.xuepoo.xyz
- Agent skill source: carryctx-skills
- Local-first. No network access by default, no account, no telemetry. State lives in
.git/carryctx/state.sqlite. - Agent-agnostic. Claude Code, OpenCode, Copilot, Codex, or a human — everyone reads and writes the same structured state.
- Git is the source of truth for code; CarryCtx is the source of truth for intent. It never rewrites history or resolves merge conflicts for you.
MIT