Introduction

A coding agent team runs on state that nobody holds reliably for long: which tasks exist and why, what depends on what, who owns what right now, and what has already been tried. When a commander plans the work, role-specialized subagents implement it, and reviewers finish it, that intent outgrows any chat window. Commit messages explain patches, not plans. Markdown notes rot the moment someone stops editing them by hand.

Chat history isn’t project state. It lives inside a provider’s context window and disappears when that window closes, and a hand-written HANDOFF.md goes stale under deadline pressure because nobody maintains it consistently.

CarryCtx manages the project lifecycle around AI coding agents and human collaborators. It durably holds what the project intends to do — contracts, dependency-aware tasks, scopes, priorities, and workflows; who does it — durable teams of commanders, role-specialized subagents, and humans; how work moves — sessions, worktrees, progress, checkpoints, handoffs, and review; and what happened — cleanup and reconciliation records, an append-only event stream, immutable decisions, analytics, and release evidence. It serves exactly the slice a caller needs over a plain CLI or MCP server.

Because everything persists locally in a single SQLite file inside your repository, continuity comes with it rather than being the point: any agent, in any window, on any worktree, picks up where the last one left off:

carryctx resume

The unit of persistence is bigger than one agent, too. A Team — a roster of agents, an optional commander, and the tasks associated with them — lives in the same database as everything else, so who is on it, what each member is working on, and what this one needs to know are durable, re-readable facts. One read-only call rebuilds the whole picture:

carryctx team context payments-squad

What CarryCtx actually is

CarryCtx is not a wrapper around an LLM, doesn’t talk to any model provider, and runs nobody’s agents. It’s a small, deterministic state machine backed by SQLite, invoked as a plain CLI. It has three defining properties:

• Local-first. No network access by default, no account, no telemetry. State lives at <git-common-dir>/carryctx/state.sqlite, so every worktree of the same repository shares it; project config lives in .carryctx/config.toml at the repository root.
• SQLite-backed. Tasks, sessions, checkpoints, progress items, decisions, handoffs, and events are all rows in a relational schema. That means they’re queryable with --json, filterable, and consistent, not free-text notes an agent might paraphrase differently every time.
• Agent-agnostic. CarryCtx doesn’t know or care whether the caller is Claude Code, Codex, OpenCode, a human at a terminal, or a CI job. Every caller identifies itself with --agent, and every caller reads and writes the same structured state.

Who this is for

CarryCtx is aimed at the point where agent work stops fitting in a prompt: a commander coordinating role-specialized subagents instead of one agent doing everything, long-running tasks that span more sessions than a single context window can hold, several agents (or a human and an agent) trading ownership of the same task, parallel lines of work across multiple Git worktrees of the same repository, and standing teams whose roster and assignments shouldn’t have to be re-declared in a prompt every time. If your work fits in one sitting with one agent, you don’t need it. If you find yourself re-explaining the plan — or re-briefing a whole team — at the start of every session, this is the layer that removes that step.

The core idea: Git owns code, CarryCtx owns intent

Git is extremely good at tracking what the code looked like at every point in history. It’s not designed to track why a task is blocked, what a previous session already tried, or which agent currently owns a piece of work. CarryCtx fills exactly that gap, and only that gap:

• Git is the source of truth for code history. CarryCtx never rewrites commits, never resolves merge conflicts, and never touches your working tree except to read its state (branch, HEAD, dirty files) for context.
• CarryCtx is the source of truth for why the code is the way it is right now: which task is active, what’s been tried, what’s still open, who’s working on it, and what decisions were made along the way.

Because the two layers don’t overlap, you can run carryctx init on any existing Git repository without disturbing anything, and you can stop using CarryCtx at any point without corrupting your Git history.

Lifecycle control, not process scheduling

This distinction matters more now that teams exist, because “multi-agent” usually implies a framework that runs the agents. CarryCtx doesn’t. The split is:

• CarryCtx owns the durable answers. Who is on this team, who the commander is, what each member is working on, what’s blocked, what was decided, and what a given member needs to know right now. All of it in SQLite, all of it still there after every window closes.
• Your external harness owns process execution. Spawning processes, scheduling and routing calls, retries, concurrency limits, and model selection stay outside CarryCtx. CarryCtx persists the control state those processes coordinate against, including task ownership, dependencies, sessions, worktrees, checkpoints, handoffs, cleanup requests, and audit history.

CarryCtx 0.11.4 does not claim a generic Automation Engine or Completion Gates. It provides the durable lifecycle substrate: dependency-gated tasks, CAS-safe claims and handoffs, bounded MCP calls, explicit cleanup policies, task correction with task edit --force, keyset-paginated events, and read-only team projections. jj colocated repositories are guarded where Git worktree operations or hooks would be unsafe. Nothing in CarryCtx schedules or runs anybody’s agents.

How it fits into your workflow

In practice the CLI shows up at the edges of a working session, not in the middle of it. At the start of a session you run carryctx resume to get oriented, then carryctx session start to open a session bound to a task. During the session you log small progress items as you go (carryctx progress todo, carryctx progress note) instead of trying to remember them for later. At a natural stopping point you record a carryctx checkpoint, and when you’re done you close out with carryctx session end. The commands are ordinary shell invocations, so they work equally well typed by a human, called from inside an agent’s tool loop, or wired into a Git hook. State is portable and mergeable too: carryctx export --snapshot writes a bundle you can carry to another clone, and carryctx import --mode merge reconciles the two offline — see Merge & Snapshots.

What you get

Running carryctx --help lists the top-level command groups. Each one maps to a concrete piece of holding intent and managing agent work:

Command	What it gives you
init	Initializes CarryCtx in a repository and writes .carryctx/config.toml
status	One-shot overview of the project: active tasks, sessions, agents, worktrees
task	Structured work units with status, priority, ownership, and dependencies, not a prose to-do list
team	Durable agent rosters: membership, an optional commander, task association, and read-only team projections
progress	Micro-progress logs attached to a task: todos, blockers, risks, notes
session	Explicit start/pause/resume/end lifecycle for an agent’s working period
checkpoint	Git-aware state snapshots: what was done, what’s remaining, what’s blocking, what’s next
resume	Reconstructs full context (task, session, checkpoint, progress, recent events) for the next agent or window
context	Dumps active task/session context in a compact or full form, meant for feeding directly into an LLM prompt
agent	Registers and manages the agents (human or AI) participating in the project
handoff	Explicit hand-off requests between agents, with accept/reject
decision	Records architectural decisions (ADRs) so the reasoning behind a choice survives past the session that made it
worktree	Binds a Git worktree to a task, so parallel work on separate branches stays correctly attributed
graph	Manages a context graph of nodes/edges for semantic queries over the project
event	Queries the immutable event log underlying everything above, for auditing
mcp	Runs a stdio Model Context Protocol server, so MCP-aware clients (Cursor, Claude Desktop, etc.) can call CarryCtx directly
stats	Agent performance analytics: session length, throughput
skill	Installs and manages executable agent skills (from a local path or repository)
preset	Installs and applies reusable capability packs: workflow SOPs, coding rules, agent personas
sync	Copies the state database to and from a local directory you name. No network stack, no server
hooks	Installs Git hooks (post-commit, prepare-commit-msg) for auto-checkpointing and task-ID-prefixed commit messages
doctor	Diagnoses and can fix project health issues: orphaned tasks, missing hooks, database drift
search	Full-text search across tasks, progress, checkpoints, and decisions, ranked by relevance

Because --agent, --session, and --task are global flags with environment variable fallbacks (CARRYCTX_AGENT, CARRYCTX_SESSION, CARRYCTX_TASK), a long-running agent process can export them once and omit them from every subsequent call. The same global set also includes --format (text, json, or markdown), --json as a shorthand for --format=json, --dry-run to simulate without writing, and --non-interactive to fail instead of prompting.

Tip

None of this requires a specific agent or IDE. If you can run a CLI, you can use CarryCtx, whether that’s from inside an agent’s tool-calling loop, a shell alias, or a Git hook.

None of this is exotic infrastructure. It’s a single binary, a SQLite file, and a set of subcommands with predictable, scriptable output. The rest of this section walks through the concepts precisely and then the exact command sequence to try it yourself.

Where to go next

• Core Concepts defines Project, Agent, Team, Session, Task, Checkpoint, and the other building blocks precisely, including their state machines.
• Quickstart walks through initializing a project, creating and claiming a task, and resuming a session end to end.
• Teams covers the team command family: membership, commanders, task association, and the two read-only projections.