CarryCtx

https://github.com/xuepoo/carryctx
Admin
CarryCtx is a local-first project lifecycle control layer for coding agents and human collaborators...
Tokens:3,753
Snippets:39
Trust Score:8.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setup: just setup

Source: https://github.com/xuepoo/carryctx/blob/main/CONTRIBUTING.md

Runs the project setup command, which installs prerequisites and configures the development environment.

```bash
just setup
```

--------------------------------

### Install CarryCtx with Homebrew

Source: https://github.com/xuepoo/carryctx/blob/main/README.md

Installs CarryCtx using Homebrew by adding the Xuepoo tap and then installing the carryctx formula.

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

--------------------------------

### Install CarryCtx with Cargo

Source: https://github.com/xuepoo/carryctx/blob/main/README.md

Installs the CarryCtx CLI from crates.io using Cargo. This is the recommended installation method.

```bash
cargo install carryctx
```

--------------------------------

### Install CarryCtx with Scoop on Windows

Source: https://github.com/xuepoo/carryctx/blob/main/README.md

Installs CarryCtx on Windows using Scoop by adding the Xuepoo bucket and then installing the carryctx package.

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

--------------------------------

### Quick Start: Initialize, create tasks, and manage a session

Source: https://github.com/xuepoo/carryctx/blob/main/README.md

Initializes a project, registers a commander agent, creates tasks, sets dependencies, claims a task, starts a session, notes progress, creates a checkpoint, and resumes the session. Every command supports the stable --format json envelope for scripts and agents.

```bash
cd your-project
carryctx init --name billing --task-prefix BILL
carryctx agent register --name commander --provider claude-code --kind commander
carryctx task create --title "Ship the CSV exporter"       # BILL-0001
carryctx task create --title "Document the CSV exporter"   # BILL-0002
carryctx task depend BILL-0002 --on BILL-0001              # plan the dependency
carryctx task claim BILL-0001 --agent commander
carryctx session start --agent commander
carryctx progress note --task BILL-0001 "Implementation started"
carryctx checkpoint --agent commander --done "Implementation started"
carryctx resume --agent commander
```

--------------------------------

### Conventional Commits examples

Source: https://github.com/xuepoo/carryctx/blob/main/CONTRIBUTING.md

Example Conventional Commit messages for feature, fix, and docs changes.

```text
feat(task): add atomic task claiming
fix(config): resolve project override precedence
docs(cli): document resume JSON schema
```

--------------------------------

### Install CarryCtx via npm or Bun

Source: https://github.com/xuepoo/carryctx/blob/main/README.md

Installs the CarryCtx CLI globally via npm or Bun. npm is an optional thin wrapper and platform-binary distribution channel; the native binary remains the primary artifact.

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

--------------------------------

### Development loop commands

Source: https://github.com/xuepoo/carryctx/blob/main/CONTRIBUTING.md

Development loop commands: fast checks, full CI pipeline, standard tests, and faster parallel tests with cargo-nextest if installed.

```bash
just check              # fast: format + clippy + check + test
```

```bash
just ci                 # full pipeline
```

```bash
cargo test              # run tests
```

```bash
cargo nextest run       # faster parallel tests (if installed)
```

--------------------------------

### Teams, Worktrees, and Handoffs: Register subagent, create team, and hand off

Source: https://github.com/xuepoo/carryctx/blob/main/README.md

Registers a subagent, creates a team, adds a member, assigns a task to the team, creates a worktree, creates a handoff, and accepts it. team status and team context are read-only projections rebuilt from durable records.

```bash
carryctx agent register --name dev-1 --provider codex --kind subagent --role implementer
carryctx team create --name core --commander commander
carryctx team member add core --agent dev-1 --role implementer
carryctx task team set BILL-0001 --team core
carryctx worktree create BILL-0001
carryctx handoff create --task BILL-0001 --target dev-1 --summary "Ready for implementation" --agent commander
carryctx handoff accept HO-0001 --claim-task --agent dev-1
```

--------------------------------

### Configure MCP client for CarryCtx

Source: https://github.com/xuepoo/carryctx/blob/main/README.md

Configuration for MCP clients like Cursor and Claude Desktop to connect to CarryCtx's stdio MCP server. Place this in the client's MCP configuration file.

```json
{
  "mcpServers": {
    "carryctx": {
      "command": "carryctx",
      "args": ["mcp"]
    }
  }
}
```
Tokens:
Raw