Quickstart

This walks through the lifecycle once: establishing the project contract, planning dependencies, registering roles, creating a task, running a session in a worktree, recording progress, handing off for review, reconciling cleanup, and resuming context. Run it inside an existing Git repository.

1. Initialize the project

cd your-project
carryctx init --name your-project --task-prefix CTX

This creates .carryctx/config.toml at the repository root and a state database inside the Git common directory (shared across all worktrees of this repo). Useful flags:

--main-branch <name> sets the branch CarryCtx treats as the default (used e.g. as the base for worktree create).
--force re-initializes even if .carryctx/ already exists.
--minimal skips the standard documentation and agent template files.
--install-skill installs the agent skill files alongside init.

2. Register an agent

Every write to project state needs an acting agent, so register one before doing anything else:

carryctx agent register --name claude-core --provider claude-code --role implementer

--name is required; --provider and --role are optional metadata. From here on, pass --agent claude-core on each command, or export it once so you don’t have to repeat it:

export CARRYCTX_AGENT=claude-core

3. Create and claim a task

carryctx task create --title "Add streaming CSV export" --priority high

This prints the new task’s display ID, CTX-0001. A task with no unfinished dependencies starts in ready; claim it to take ownership:

carryctx task claim CTX-0001
carryctx task start CTX-0001

task claim sets you as owner; task start moves the status from ready to in_progress and automatically binds the task to your current context (so subsequent commands can omit --task).

For a task that is already completed or cancelled, ordinary edits are blocked. An authorized owner can make a correction with carryctx task edit CTX-0001 --title "Corrected title" --force; the correction is recorded in the audit log.

4. Start a session

carryctx session start --agent claude-core --task CTX-0001

This opens a session in Active state, bound to the task. If a session is already active and you don’t want an error, add --reuse. You can also bind a session to a specific worktree with --worktree <path>.

5. Do the work, log progress as you go

As you make changes, log small progress items rather than waiting until the end:

carryctx progress todo "Write unit tests for the streaming writer"
carryctx progress note "Chunked upload caps out at 5MB parts on S3"

When you reach a natural stopping point (a good commit, end of a work block, or before switching context), record a checkpoint. This is the record that a future session actually resumes from:

carryctx checkpoint \
  --done "Implemented CSV writer, added unit tests" \
  --remaining "Add streaming support for >1M rows" \
  --next "Wire the writer into the streaming pipeline"

By default this also runs git add/git commit to capture the corresponding file changes (pass --no-git to skip that, or --include-diff to embed the uncommitted diff directly in the checkpoint record).

6. End the session

carryctx session end --summary "Implemented CSV writer and tests, streaming still open"

This cleanly terminates the session (Active → Ended). Now imagine the window closes, or a different agent picks this up tomorrow.

7. Resume in a new session

In a fresh window (or a different agent entirely), the very first command should be:

carryctx resume

With no --task/--session flags, resume finds the most recently active session for the project, resolves its bound task, and pulls together the latest checkpoint, open progress items, recent events, and current Git branch/HEAD. In text mode this is the pretty-printed JSON of that reconstructed context:

{
  "schema_version": 1,
  "command": "resume",
  "success": true,
  "data": {
    "projectId": "01J...",
    "currentSession": { "id": "01J...", "state": "ended", "taskId": "01J..." },
    "currentTask": { "id": "01J...", "displayId": "CTX-0001", "status": "in_progress" },
    "latestCheckpoint": {
      "done": ["Implemented CSV writer, added unit tests"],
      "remaining": ["Add streaming support for >1M rows"],
      "next": ["Wire the writer into the streaming pipeline"]
    },
    "progress": [
      { "kind": "todo", "content": "Write unit tests for the streaming writer" },
      { "kind": "note", "content": "Chunked upload caps out at 5MB parts on S3" }
    ],
    "recentEvents": ["..."],
    "branch": "feature/csv-export",
    "head": "32ac891..."
  }
}

Useful flags on resume:

--task <ref> or --session <ref> target a specific task/session instead of the most recently active one.
--compact produces a shorter summary; --full includes extensive historical logs and file paths.
--include-diff adds the uncommitted Git diff to the output.
--max-events <n> caps how many recent events come back (defaults to 10).
--start-session automatically opens a new session right after printing the context, so you don’t need a separate session start call.

With the checkpoint and progress items in hand, the new session (or agent) restarts work with the same picture the previous one had, no re-reading of chat logs required.

8. Optional: put more than one agent on it

If several agents work this repository, register them as a team once and the roster persists like everything else:

carryctx agent register --name commander-1 --provider claude-code --kind commander
carryctx team create --name payments-squad --commander commander-1
carryctx team member add payments-squad --agent claude-core --role backend
carryctx task team set CTX-0001 --team payments-squad

From then on, a commander reads the team’s whole picture — members, tasks, dependencies, blockers, decisions, handoffs — in one read-only call, and can narrow it to a single member before handing that slice to them:

carryctx team context payments-squad
carryctx team context payments-squad --agent-for claude-core

Neither command writes anything. Dispatching the work to those agents is your harness’s job, not CarryCtx’s.

9. Reconcile and release

When work is reviewed and a task is complete, v0.11.4 (since v0.8) can create a persistent cleanup request according to project policy. Run carryctx worktree cleanup list to inspect pending or blocked requests and carryctx worktree cleanup run to retry safe reconciliation. A path that is already gone is reconciled idempotently as already removed, and its stale registration is cleaned up; dirty worktrees, active sessions, locks, missing Git metadata, and jj-colocated repositories remain visible blockers. An unknown registration is a lookup error, not an already-removed worktree. Use carryctx stats and carryctx event list to retain audit and analytics evidence for the release.

10. Merge state from another clone

Project state is portable and mergeable. When the same project lives in more than one clone, export a snapshot from one and merge it into the other — a semantic three-way merge over rows, not a line-level merge of JSONL:

carryctx export --pack-format dir -o ./pack --snapshot
# move ./pack (or the snapshot ref) to the other clone yourself
carryctx import ./pack --mode merge

Blocking conflicts, if any, stage for review: inspect them with carryctx conflict list, then settle each with carryctx conflict resolve and carryctx conflict apply. Native git merge of snapshot commits is not supported. The full workflow, snapshot refs, and exit codes are in Merge & Snapshots.

Next steps

Project Lifecycle covers init, status, doctor, and the other commands that manage the project itself in more depth.
Core Concepts is the reference for every state and transition used above.
Teams documents the full team surface, including the JSON shape of both projections.