# CarryCtx
**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.
```bash
carryctx resume
```
```text
Task 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.
## Installation
### Cargo (recommended)
```bash
cargo install carryctx
```
### npm
```bash
npm install -g carryctx
# or
bun add -g carryctx
```
### GitHub Releases
Download the prebuilt binary for your platform from the [releases page](https://github.com/Xuepoo/carryctx/releases).
### Homebrew
```bash
brew tap Xuepoo/tap https://github.com/Xuepoo/homebrew-tap.git
brew install carryctx
```
### Scoop (Windows)
```powershell
scoop bucket add Xuepoo https://github.com/Xuepoo/scoop-bucket.git
scoop install carryctx
```
### AUR (Arch Linux)
```bash
yay/paru -S carryctx
yay/paru -S carryctx-bin
```
## Quick start
```bash
cd 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
```
## Why not just Markdown notes or a `HANDOFF.md`?
| 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.
## What's inside
| `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 |
| `team` | Persistent agent teams — roster, commander, task assignment, and read-only status/context projections that survive every session |
| `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](https://modelcontextprotocol.io) 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` | Copy the state database to and from a local `--remote` path — a plain file copy, no network stack in the binary |
## Full-Text Search
Find prior work by content without remembering which task or branch contained it:
```bash
carryctx search "markdown worker protocol"
carryctx search aria-owns --type decision --json
carryctx search "auth flow" --status in_progress --assignee claude-code
```
Results 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.
## Agent Teams
One agent per repo was never the real shape of the work. A commander plans, subagents implement, review, and write docs — and every one of them loses its memory when its window closes.
A CarryCtx Team is a durable roster that outlives all of them. It lives in the same `state.sqlite` as your tasks, so it survives closed sessions, new windows, and linked worktrees without a re-introduction:
```bash
carryctx team create --name core --commander commander-1
carryctx team member add core --agent dev-1 --role implementer
carryctx team member add core --agent reviewer-1 --role reviewer
carryctx task team set CTX-0042 --team core
```
Then ask what the team is actually doing — a read-only projection, rebuilt from durable records:
```bash
carryctx team status core # roster, active sessions, open tasks, counts
carryctx team context core # commander view: full coordination picture
carryctx team context core --agent-for dev-1 # just what that member needs
carryctx team context core --task CTX-0042 # just what that task needs
```
`team status` and `team context` open the database read-only and write nothing — no events, no claims, no sessions. A commander gets the whole graph; `--agent-for` and `--task` narrow every collection consistently so a subagent is handed its slice instead of the entire project.
**CarryCtx records the team; it does not run it.** Spawning processes, routing work, retries, concurrency limits, and model selection stay with your harness. CarryCtx owns the durable answer to _who is on this team, what are they working on, and what does each one need to know_ — and deliberately nothing beyond that. No scheduler, no worker runtime, no prompt cache.
## Shell Completions
Enable tab-completion for all commands and flags:
```bash
# 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
## Git Hooks
Install CarryCtx git hooks to auto-checkpoint on commit and prefix commit messages with the active task ID:
```bash
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)
```
## Diagnostics
```bash
carryctx doctor # check project health (git, db, hooks, orphaned tasks)
carryctx doctor --json # machine-readable output
```
## Agent Skill Setup
Load the CarryCtx skills to give your coding agent first-class CarryCtx awareness. All skills ship from [carryctx-skills](https://github.com/Xuepoo/carryctx-skills) via the [Vercel Labs Skills CLI](https://github.com/vercel-labs/skills).
List available skills:
```bash
npx skills add Xuepoo/carryctx-skills --list
```
Install all skills for all detected agents:
```bash
npx skills add Xuepoo/carryctx-skills --all
```
Install selected skills for specific agents:
```bash
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-copilot
```
Use one skill without installing it:
```bash
npx skills use Xuepoo/carryctx-skills --skill carryctx-core
```
The skills teach agents to manage sessions, tasks, progress, and checkpoints through CarryCtx — enabling persistent context across agent restarts and worktree switches.
## Documentation
- Full docs & guides: [carryctx.xuepoo.xyz](https://carryctx.xuepoo.xyz)
- Agent skill source: [carryctx-skills](https://github.com/Xuepoo/carryctx-skills)
## Principles
- **Local-first.** No network access at all — the binary ships no network stack. 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.
- **Management, not orchestration.** CarryCtx persists teams, tasks, and context. Your harness runs the agents. It stays a tool, not a framework you have to adopt.
## License
MIT