--- name: carryctx-core description: Core CarryCtx capability. Persistent project context and continuity manager for coding agents. Helps agents manage structured tasks, track progress, save checkpoints, maintain context across sessions and Git worktrees, and coordinate durable agent teams. Use when starting work, tracking task progress, creating checkpoints, switching worktrees, scanning code dependency graphs, running MCP stdio servers, applying presets, restoring project state, searching prior tasks/checkpoints/decisions by content, or reading team membership and per-agent team context. license: MIT metadata: author: Xuepoo version: "0.4.0" --- # CarryCtx Core Skill CarryCtx provides first-class project state and context continuity for AI coding agents. It enables agents to manage tasks, track granular progress, create checkpoint snapshots, maintain AST code dependency graphs, run stdio MCP servers, apply workflow presets, and seamlessly preserve context across session restarts and Git worktrees. ## When to Apply Use CarryCtx commands when: - **Starting a new task or session**: Register agent identity, start session, and restore context (`carryctx resume`). - **Managing project tasks**: Create, claim, start, complete, block, or cancel tasks (`carryctx task ...`). - **Tracking granular progress**: Record structured `todo`, `block`, `risk`, and `note` items. - **Saving state / Checkpointing**: Capture current work progress, git status, and remaining work before ending sessions or switching focus. - **Code Graph Exploration**: Scan AST module dependencies (`carryctx graph scan`) and export Mermaid/DOT/ASCII diagrams (`carryctx graph export`). - **AI Agent Tool Integration (MCP)**: Expose project context to Cursor / Windsurf / AGY via Model Context Protocol stdio server (`carryctx mcp`). - **Standardizing Workflows (Presets)**: List, inspect, and apply project workflow blueprints, coding rules, and agent personas (`carryctx preset ...`). - **Parallel task work**: Create and isolate tasks in dedicated Git worktrees (`carryctx worktree ...`). - **Diagnosing health issues**: Run `carryctx doctor` to surface orphaned tasks, missing hooks, and DB problems. - **Pruning old data**: Use `carryctx project prune` to clean up completed tasks and keep the DB lightweight. - **Agent Analytics**: Use `carryctx stats` to audit agent session lengths, task metrics, and export Markdown/CSV reports. - **Finding prior work by content**: Use `carryctx search ""` to find tasks, progress items, checkpoints, or decisions by keyword instead of hand-writing SQL or grepping commit messages. - **Coordinating multiple agents (0.6.0+)**: Maintain durable teams and read who is on them and what each member holds (`carryctx team ...`). See [references/team-coordination.md](references/team-coordination.md). ## Prerequisites 1. Install CarryCtx CLI (`cargo install carryctx` or pre-built binary). 2. Initialize CarryCtx in the project repository: `carryctx init`. ## Quick Reference | Action | Command | Purpose | | -------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------- | | **Agent Setup** | `carryctx agent register --name "$(whoami)" --provider "claude-code"` | Register agent identity | | **Current Agent** | `carryctx agent current` | Show active agent identity | | **Start Session** | `carryctx session start` | Begin tracked working session | | **Resume Context** | `carryctx resume` | Fetch current task, progress & next actions | | **Create Task** | `carryctx task create --title "..." [--depends-on CTX-0001]` | Define a new task | | **Claim Task** | `carryctx task claim CTX-0001` | Assign task to current agent | | **Edit Task** | `carryctx task edit CTX-0001 [--title ...] [--priority ...] [--description ...]` | Update task title, priority, or description | | **Start Task** | `carryctx task start CTX-0001` | Mark task as in-progress | | **Track Progress** | `carryctx progress "..."` | Record structured progress item | | **Checkpoint** | `carryctx checkpoint --done "..." --remaining "..."` | Save semantically rich state snapshot | | **Scan Code Graph** | `carryctx graph scan` | Extract AST dependencies into SQLite graph | | **Export Graph** | `carryctx graph export --type ` | Render dependency graph (PNG/SVG/ASCII) | | **MCP Stdio Server** | `carryctx mcp` | Launch MCP stdio server with 6 agent tools | | **Apply Preset** | `carryctx preset apply ` | Inject workflow SOPs, rules, or personas | | **Worktree** | `carryctx worktree create CTX-0001` | Create isolated git worktree for task | | **End Session** | `carryctx session end` | Safely end session with checkpoint | | **Doctor** | `carryctx doctor` | Diagnose project health | | **Install Hooks** | `carryctx hooks install` | Auto-checkpoint on every git commit | | **Prune Data** | `carryctx project prune --older-than 30` | Clean up old completed tasks | | **Agent Stats** | `carryctx stats [--markdown] [--output file.csv]` | View metrics and export performance reports | | **Decision** | `carryctx decision add --title "..." --task CTX-0001` | Record architectural decision | | **Handoff** | `carryctx handoff create --target --task CTX-0001` | Transfer work between agents | | **Session Pause** | `carryctx session pause` | Pause active session timer | | **Session Resume** | `carryctx session resume` | Resume a paused session | | **Search** | `carryctx search "" [--type task\|progress\|checkpoint\|decision]` | Full-text search across tasks, progress, checkpoints, decisions | | **Create Team** | `carryctx team create --name core [--commander ]` | Create a durable project-scoped team | | **Team Membership** | `carryctx team member add core --agent sub-1 --role backend` | Add or remove a team member | | **Set Commander** | `carryctx team commander set core --agent cmd-1` (or `--clear`) | Set or clear the team commander | | **Team Status** | `carryctx team status [core]` | Read-only: members, kinds, sessions, active tasks, counts | | **Team Context** | `carryctx team context [core] [--agent-for ] [--task CTX-0001]` | Read-only: tasks, deps, blockers, checkpoints, decisions | | **Task Team** | `carryctx task team set CTX-0001 --team core` (or `unset`) | Associate or clear a task's team | ## Output Behavior (0.5.2+) Text output (the default `--format text`) is **compact by design**: entity commands print one short line per record (`Task created: CTX-0321`, `agent current` prints just the name, lists show `display_id`, status, and a clipped title/summary) so agent context stays small. When full records are needed: - `--verbose` (global flag) or `[output] verbose = true` in `.carryctx/config.toml` restores the full pretty-printed record. - `--fields display_id,status,summary` (global flag) or the per-command `[output.fields]` table trims records to an allowlist in text and JSON. - `--format json` always returns the complete envelope. JSON output is unchanged and remains the machine contract: every success is a single envelope on stdout, every error a single envelope on stderr. ## Standard Agent Workflow ### 1. Session Initialization & Context Restoration At the start of any interaction or after an agent restart: ```bash # Register & set identity if not already configured carryctx agent current || carryctx agent register --name "claude" --provider "claude-code" # Start session and load current context carryctx session start carryctx resume ``` To pause and resume sessions: ```bash carryctx session pause # Pause active session (timer stops) carryctx session resume # Resume a paused session carryctx session end # End session with optional checkpoint carryctx session abandon # End session without checkpoint ``` ### 2. Code Dependency Analysis (Graph Subsystem) Before modifying code or refactoring modules: ```bash # 1. Scan codebase AST dependencies carryctx graph scan # 2. Export sub-graph centered around a specific module carryctx graph export --type mermaid --focus "src/application/stats.rs" --depth 2 # 3. Export module-level compact ASCII architectural overview carryctx graph export --type ascii --compact ``` ### 3. Workflow Presets & Rule Injection Inject standard operating procedures or coding guidelines: ```bash # List available workflow presets carryctx preset list # Apply a standard bugfix workflow preset to current project carryctx preset apply workflows/bugfix ``` ### 4. Task Lifecycle ```bash # List open tasks carryctx task list --status ready # Claim & start task carryctx task claim CTX-0001 carryctx task start CTX-0001 # Mark task finished after verification carryctx task complete CTX-0001 ``` ### 5. Granular Progress Tracking As work progresses, log structured progress items: ```bash carryctx progress todo "Write unit test for auth middleware" carryctx progress todo "Implement JWT token validation" carryctx progress block "Waiting for API endpoint spec confirmation" carryctx progress risk "Breaking change in upstream dependency" carryctx progress note "Used LRU cache to optimize token lookups" # Mark a todo as completed: carryctx progress complete PX-0001 ``` ### 6. Creating Checkpoints Save state before ending a session, switching tasks, or handing off work: ```bash carryctx checkpoint \ --done "Finished backend authentication endpoints" \ --remaining "Frontend login form integration" \ --blocker "None" ``` ### 7. Worktree Parallelism When working on independent tasks simultaneously: ```bash carryctx worktree create CTX-0002 # Switches to isolated worktree directory linked to CTX-0002 ``` ### 7a. Durable Agent Teams (0.6.0+) A team is project-scoped state in the shared `state.sqlite`, so it outlives sessions, terminal windows, and linked worktrees. CarryCtx is the **management and persistence layer**: it records who is on a team, what each member holds, and what each needs to know. Spawning processes, routing work, retries, concurrency limits, and worktree creation belong to the harness running the agents — 0.6.0 ships no scheduler, worker runtime, or lease/heartbeat machinery. ```bash # Identity with an execution kind carryctx agent register --name cmd-1 --provider opencode --kind commander carryctx agent register --name sub-1 --provider opencode --kind subagent --role backend # Build the team; the commander must be a member of its own team carryctx team create --name core --commander cmd-1 carryctx team member add core --agent sub-1 --role backend # Associate tasks (never changes lifecycle, ownership, deps, or scopes) carryctx task create --title "Backend API" --team core --required-role backend carryctx task team set CTX-0007 --team core ``` `carryctx team status` and `carryctx team context` are **read-only projections**: they open the database read-only, run no migrations, and write nothing — no events, no claims, no sessions. Call them as often as you need, from any agent. ```bash carryctx team status core # members, kinds, sessions, active tasks, counts carryctx team context core # tasks, deps, blockers, checkpoints, decisions carryctx team context core --agent-for sub-1 # the same picture narrowed to one member ``` An agent may hold **several** `in_progress` tasks at once; `claim`/`start`/`assign` never fail on a task count. Capacity policy is the commander's or the harness's concern. Because these projections are rebuilt from durable records, record progress and checkpoints **as you work** — a subagent that dies silently leaves nothing behind. Full command surface, JSON shapes, and semantic rules: [references/team-coordination.md](references/team-coordination.md). ### 7b. Recording Decisions & Handoffs Capture architectural decisions and hand off work between agents: ```bash # Record an architectural decision (ADR) linked to a task carryctx decision add --title "Use SQLite for storage" --task CTX-0001 # List or search decisions carryctx decision list carryctx decision search --keyword SQLite # Mark a decision as superseded by a newer one carryctx decision supersede DEC-0001 --by DEC-0002 # Create a handoff to transfer work to another agent carryctx handoff create --target --summary "Implement the API" --task CTX-0001 # Accept, reject, or close a handoff carryctx handoff accept HO-0001 carryctx handoff reject HO-0001 --reason "Not my area" carryctx handoff close HO-0001 ``` ### 7c. Full-Text Search Across Project History Find prior work by content, not by remembering which branch or task touched it. Searches task titles/descriptions, progress items, checkpoint notes, and decisions, all ranked by relevance: ```bash # Search everything carryctx search "markdown worker protocol" # Scope to one entity kind carryctx search "retry backoff" --type checkpoint # Narrow by the owning task's status or owner agent carryctx search "auth" --status in_progress carryctx search "auth" --assignee claude-code ``` Each hit includes the owning task's display ID, status, and (when known) the branch it was worked on — use this before starting related work to avoid duplicating already-solved problems, and before a handoff to point the receiving agent at the exact checkpoint or decision that explains a prior choice. ### 8. Ending Session & Reporting ```bash # End working session carryctx session end # Export project stats report for PR description or documentation carryctx stats --markdown --output /tmp/project_stats.md ``` ### 9. Model Context Protocol (MCP) Integration To hook CarryCtx directly into Cursor / Windsurf / AGY: ```json { "mcpServers": { "carryctx": { "command": "carryctx", "args": ["mcp"] } } } ``` Exposed MCP Tools: - `carryctx_graph_explorer`: Query, scan, and export the project Context Graph - `carryctx_context_manager`: Manage persistent context, checkpoints, and state snapshots - `carryctx_task_manager`: Manage project tasks, dependencies, and priorities - `carryctx_progress_tracker`: Manage task progress, notes, and blockers - `carryctx_decision_logger`: Log and search architectural decision records - `carryctx_project_admin`: Manage project database, stats, cold storage archiving, and config ### 10. Debugging & Troubleshooting Enable structured debug logging to diagnose issues: ```bash # Show debug logs for CarryCtx operations export RUST_LOG=carryctx=debug carryctx task list # See debug output before command results # Show only errors export RUST_LOG=error carryctx status # Run diagnostics carryctx doctor # Check project health carryctx doctor --json # Machine-readable diagnostic output ``` ## Best Practices for Coding Agents 1. **Always run `carryctx resume` when starting**: Re-orients agent to current task and progress immediately. 2. **Scan code graph before large refactors**: `carryctx graph scan` prevents broken upstream dependencies. 3. **Explicitly claim tasks**: Prevents duplicate execution when multiple agents work on the same repository. 4. **Use structured progress items**: Keep `todo`, `done`, and `block` updated during execution steps. 5. **Checkpoint before stopping**: Always create a checkpoint before yielding control or completing complex multi-step work. 6. **Run `carryctx doctor` on first use or after upgrade**: Surfaces setup gaps before they cause runtime errors. 7. **Record durably while working, not at exit**: `team context`, `resume`, and handoffs are rebuilt from persisted progress items, checkpoints, and decisions. Work that was never recorded is indistinguishable from work never done — and a process killed before its final checkpoint leaves nothing for its successor. 8. **Read team state before dispatching or claiming**: `carryctx team status` and `carryctx team context` cost nothing (read-only, no writes) and are the only reliable statement of who is live and what they hold.