# Use Carryctx > Coordinate multi-step coding work across agents with CarryCtx, the local-first durable project lifecycle manager. Load once per main session when planning or coordinating engineering work: plan as the commander, assign durable tasks with dependencies, teams, and scopes, dispatch implementation to subagents in isolated Git worktrees, and accept results by reading state back from carryctx instead of trusting subagent self-reports. - Skill: `xuepoo/use-carryctx` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add xuepoo/use-carryctx` - Raw SKILL.md: https://api.skillmd.com/api/skills/xuepoo/use-carryctx/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: Xuepoo (https://skillmd.com/u/xuepoo) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/xuepoo/use-carryctx --- # Use CarryCtx CarryCtx is local-first durable project lifecycle management for commander/subagent teams. It persists tasks, roles, sessions, checkpoints, handoffs, cleanup outbox requests, and audit state in `/carryctx/state.sqlite`, shared by every agent and linked worktree on the repository. The harness still executes agents and controls spawning, routing, retries, and concurrency; CarryCtx is the management and persistence layer, not a generic Automation Engine or Completion Gates system. This skill is loaded once per main session. ## When to Apply Apply at main-session start for any multi-step engineering effort, especially: > **Prerequisite — run inside the target Git repository.** Every carryctx > command must execute from within that project's repo clone (state lives at > `/carryctx/state.sqlite`). From a non-repo directory every > command fails with `GIT_ERROR` exit 4. In multi-repo workspaces, `cd` into > each product repository first — state is per-repo, never workspace-wide. - Planning and splitting an effort into tasks with dependencies and owners. - Dispatching implementation to subagents while keeping your own context lean. - Running parallel work streams that need isolation (Git worktrees). - Continuing prior work: restoring context, accepting handoffs, finding past decisions and checkpoints by content. ## Commander Doctrine You (the main-session agent) are the **commander**. Subagents implement; you do not. The loop: 1. **Plan** — decompose the goal into tasks with explicit dependencies and scopes. Small one-line fixes stay inline; batching tightly-coupled tasks to one subagent beats fan-out. 2. **Assign** — encode the plan durably in carryctx so nothing depends on your conversation surviving: `task create` with `--depends-on`, `--team`, `--required-role`, and `task scope add` for conflict detection. 3. **Dispatch** — give each subagent exactly its slice: a task ID plus `carryctx team context --agent-for ` output. Prefer running each subagent in its own worktree: `carryctx worktree create ` creates `/.worktrees/` on a `carryctx/` branch. 4. **Accept & verify** — never trust a subagent's self-report. Read state back: `team status`, `team context`, `task show`, `search`. Verify the diff and run the tests yourself before `task complete`. Supporting rules: - **Record durably because subagents die silently.** A process killed before its final checkpoint leaves nothing behind. Require subagents to append `progress todo/note/block/risk`, `checkpoint`, and `decision add` records as they work — `team context` can only rebuild what was written down. - **Keep your own context lean.** Outline before reading files, prefer compact output (`--compact`, `--fields display_id,status,title`), re-read `team status` between rounds instead of holding state in conversation. - **Close what you open.** A task left `in_progress` after its agent stops is indistinguishable from active work; end sessions cleanly, checkpoint before merging branches away. Bootstrap once, then operate the loop: ```bash carryctx init # first time only carryctx agent register --name "$(whoami)" --provider opencode --kind commander carryctx session start carryctx resume --compact # restore prior context carryctx task create --title "Backend API" --team core --required-role backend carryctx task create --title "Login form" --depends-on CTX-0002 carryctx worktree create CTX-0002 # isolate implementation ``` ## Core Commands Flags below are verified against CarryCtx v0.9.0. Writes require identity: pass `--agent ` (or export `CARRYCTX_AGENT`) — listings never filter by it implicitly. ```bash # Plan & track carryctx task create --title "..." [--priority high] [--team core] \ [--required-role backend] [--depends-on CTX-0001] carryctx task show CTX-0002 # full detail + records carryctx task claim CTX-0002 && carryctx task start CTX-0002 carryctx task complete CTX-0002 # after agent/harness verification; transitions task and attempts configured cleanup carryctx task edit CTX-0002 --title "..." --force # audited terminal correction # Read team state back (never trust self-reports) carryctx team status [core] carryctx team context [core] [--agent-for sub-1] [--task CTX-0002] # Durable breadcrumbs written by subagents as they work carryctx progress note|block|risk "..." --task CTX-0002 carryctx checkpoint --done "..." --remaining "..." --task CTX-0002 # Isolation & continuity carryctx worktree create CTX-0002 # .worktrees/, branch carryctx/ carryctx export --pack-format dir -o ./pack/ # 0.9.0 portable state (since 0.8.2); import re-anchors paths carryctx worktree cleanup list # durable cleanup outbox carryctx worktree cleanup show # request by ID or task reference carryctx worktree cleanup run # retry deferred, blocked, or failed cleanup carryctx handoff create --agent cmd-1 --target sub-1 --task CTX-0002 --summary "..." ``` Everything else — dependency kinds (`strong`/`informational`), file scopes and conflict detection, task statuses, blockers, decisions, search, event audit, presets/rules/personas in `.carryctx/`, error recovery — is documented in the references below. Consult them when operating in that area; do not guess flags. ## References Read the focused guide when operating in that area: - [references/command-reference.md](references/command-reference.md) — full command table for all subcommands and flags (verified against v0.9.0). - [references/task-lifecycle.md](references/task-lifecycle.md) — states, transitions, dependency gating, scopes, team metadata. - [references/team-coordination.md](references/team-coordination.md) — team semantics, read-only projections, dispatch patterns, recording discipline. - [references/sessions-and-checkpoints.md](references/sessions-and-checkpoints.md) — session lifecycle, stale detection, checkpoint policy. - [references/handoffs.md](references/handoffs.md) — writing and taking over handoffs, routing documents, accept/reject/close. - [references/presets-rules-personas.md](references/presets-rules-personas.md) — installing SOPs, domain rules, and personas into `.carryctx/`. - [references/troubleshooting.md](references/troubleshooting.md) — error codes, recovery, diagnostics.