CarryCtx

Manage what your agent team intends, who does it, and what happened — not their chat logs.

AI 编码 Agent 的意图与管理层。

A chat transcript dies with its window, and it was never project state to begin with. The durable questions are: what is this agent team trying to do, who is doing it right now, and what actually happened. CarryCtx answers all three from a single local SQLite database and serves exactly the right slice of it to any agent, in any session, through CLI or MCP.

CarryCtx is the intent & management layer for AI coding agents:

• WHAT — structured, dependency-aware tasks with priorities and workflows. The lifecycle (planned → ready → in_progress → completed) is enforced by the store itself: strong dependencies gate both start and completion, so work can't be born done or closed over an open blocker.
• WHO — durable teams of commanders and role-specialized subagents, plus explicit handoffs between agents through an enforced state machine (Open → Accepted/Rejected → Closed). Concurrent claims are settled with compare-and-set updates: exactly one winner, ever.
• WHAT HAPPENED — an append-only, keyset-paginated event stream, Git-aware checkpoints, recorded decisions, and full-text search across tasks, progress, checkpoints, and decisions. Every mutation is auditable; history never silently rewrites itself.

CarryCtx records and serves state; it does not run your agents. There is no scheduler, no worker runtime, no prompt cache, and no cloud. Your harness spawns the processes — CarryCtx makes sure every one of them arrives knowing exactly what it needs to know.

English | 简体中文

Pillars

Installation

Cargo (recommended)

cargo install carryctx

npm

npm install -g carryctx
# or
bun add -g carryctx

GitHub Releases

Download the prebuilt binary for your platform from the releases page.

Homebrew

brew tap Xuepoo/tap https://github.com/Xuepoo/homebrew-tap.git
brew install carryctx

Scoop (Windows)

scoop bucket add Xuepoo https://github.com/Xuepoo/scoop-bucket.git
scoop install carryctx

AUR (Arch Linux)

AUR publication is currently disabled because of an upstream AUR outage. Use Cargo or the GitHub Releases binaries until publication resumes.

The carryctx and carryctx-bin AUR packages are unavailable until publication resumes.

Quick start

cd your-project
carryctx init                                          # creates .carryctx/ + shared Git state
carryctx agent register --name my-agent --provider claude-code
carryctx task create --title "Ship the CSV exporter"   # CTX-0001
carryctx task depend CTX-0002 --on CTX-0001            # gate work on prerequisites
carryctx task claim CTX-0001 --agent my-agent
carryctx resume --agent my-agent                       # pick up exactly where things stand

Every command speaks --format json with a stable envelope, so scripts and agents consume the same surface humans do.

Teams: a commander and its subagents

One agent per repo was never the real shape of the work. A commander plans; subagents implement, review, and write docs. A CarryCtx team is a durable record of that structure — it lives in the same state.sqlite as your tasks, so it survives closed sessions, new windows, and linked worktrees without a re-introduction:

carryctx agent register --name commander-1 --provider claude-code --kind commander
carryctx agent register --name dev-1 --provider codex --kind subagent --role implementer
carryctx team create --name core --commander commander-1
carryctx team member add core --agent dev-1 --role implementer
carryctx task team set CTX-0042 --team core

Then ask what the team is actually doing — a read-only projection, rebuilt from durable records:

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. A commander gets the whole graph; --agent-for and --task narrow every collection consistently, so a subagent receives its slice instead of the entire project. When work moves between agents, a handoff carries it through an enforced lifecycle instead of a hopeful ping:

carryctx handoff create --task CTX-0042 --target dev-1 --summary "Ready for review" --agent commander-1
carryctx handoff accept HO-0007     # Open → Accepted, atomically audited

CarryCtx records the team; it does not run it. Spawning processes, routing work, retries, and model selection stay with your harness.

MCP: plug into any MCP client

CarryCtx ships six MCP tools over stdio — carryctx_task_manager, carryctx_progress_tracker, carryctx_context_manager, carryctx_decision_logger, carryctx_graph_explorer, and carryctx_project_admin — exposing the same durable state to Cursor, Claude Desktop, or any other MCP client:

{
  "mcpServers": {
    "carryctx": {
      "command": "carryctx",
      "args": ["mcp"]
    }
  }
}

What's inside

Full-Text Search

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 --assignee my-agent

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.

Shell Completions

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-Expression

Git Hooks

Install 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)

Diagnostics

carryctx doctor              # check project health (git, db, hooks, orphaned tasks)
carryctx doctor --json       # machine-readable output

Agent Skill Setup

Give your coding agent first-class CarryCtx awareness with use-carryctx — the single entry-point skill shipped from carryctx-skills via the Vercel Labs Skills CLI. One install covers the full surface: commander doctrine plus focused references for tasks, teams, sessions/checkpoints, handoffs, presets/rules/personas, and troubleshooting.

List available skills:

npx skills add Xuepoo/carryctx-skills --list

Install use-carryctx for all detected agents:

npx skills add Xuepoo/carryctx-skills --all

Or install that one skill for specific agents only:

npx skills add Xuepoo/carryctx-skills \
  --skill use-carryctx \
  --agent codex \
  --agent claude-code \
  --agent cursor \
  --agent github-copilot

Use the skill without installing it:

npx skills use Xuepoo/carryctx-skills --skill use-carryctx

Load it once per main session, at the start of any multi-step engineering effort. The skill casts your main-session agent as the commander: plan the work as durable CarryCtx tasks, dispatch implementation to role-specialized subagents (each preferably isolated in its own Git worktree), then accept results by reading state back through team status, team context, and task show instead of trusting self-reports.

Why not just Markdown notes or a HANDOFF.md?

Git owns code history; CarryCtx owns intent — why the code is the way it is, who owns it next, and what remains.

Documentation

• Full docs & guides: carryctx.xuepoo.xyz
• Agent skill source: carryctx-skills

Principles

• Management layer, not chat memory. CarryCtx holds intent, ownership, and history as queryable state — the thing chat windows were never going to be.
• Local-first. No network access at all — the binary ships no network stack. No account, no telemetry, no lock-in. State lives in <git-common-dir>/carryctx/state.sqlite and is shared by linked worktrees.
• Agent-agnostic. Claude Code, OpenCode, Copilot, Codex, or a human — everyone reads and writes the same structured state, over CLI or MCP.
• Enforced by the store, not by convention. Lifecycles, dependencies, handoffs, and claims are guarded in SQLite transactions — exactly-one-winner under concurrency.
• 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