carryctx 0.3.1

Local-first memory for coding agents — resume tasks, checkpoints, and context across windows, sessions, and worktrees.
docs.rs failed to build carryctx-0.3.1
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

CarryCtx

Your coding agent forgets everything the moment its window closes. CarryCtx doesn't.

You close Claude Code. Tomorrow's session — or a teammate's, or a different agent entirely — has no idea what you were doing, what's done, what's blocked, or what branch you were on. Chat history isn't project state. Commit messages don't explain intent. Markdown notes go stale the moment you stop updating them by hand.

CarryCtx is a local-first CLI that gives coding agents a real memory: structured tasks, progress, decisions, and Git-aware checkpoints, all persisted in a single SQLite file inside your repo. Any agent, in any window, on any worktree, runs one command and picks up exactly where the last one left off.

carryctx resume

Task CTX-0014 — Add streaming CSV export
Owner: claude-core · Status: in_progress

Last checkpoint (12m ago):
  Done:      Implemented CSV writer, added unit tests
  Remaining: Add streaming support for >1M rows
  Blocker:   None

Git: branch feature/csv-export, HEAD 32ac891, 2 files dirty
Next: Wire the writer into the streaming pipeline

No re-reading chat logs. No "catch me up" prompts. No stale hand-off doc.

English | 简体中文

Installation

Cargo (recommended)

cargo install carryctx

npm

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

GitHub Releases

Download the prebuilt binary for your platform from the releases page.

Homebrew

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

Scoop (Windows)

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

AUR (Arch Linux)

yay/paru -S carryctx
yay/paru -S carryctx-bin

Quick start

cd your-project
carryctx init
carryctx agent register --name my-agent --provider claude-code
carryctx task create --title "My first task"
carryctx task claim CTX-0001
carryctx session start
carryctx resume

Why not just Markdown notes or a HANDOFF.md?

Markdown hand-off doc Chat history CarryCtx
Survives a closed window Only if someone remembers to write it No Yes
Machine-queryable No — free text No Yes — SQL + --json
Tracks Git state automatically No No Yes (branch, HEAD, dirty files, diff stats)
Works across different agents Depends on convention No — tied to one tool's context Yes — agent-agnostic
Detects stale state No No Yes (carryctx doctor)
Leaves your machine No Depends on provider Never — 100% local

CarryCtx doesn't replace Git and it doesn't run your agent. It's the layer in between: Git owns code history, CarryCtx owns why the code is the way it is right now.

What's inside

Command What it gives you
task, progress, depend Structured work units with dependencies, blockers, and micro-progress logs — not a prose to-do list
checkpoint, resume, context Git-aware state snapshots and LLM-ready context dumps
session, agent, handoff Multi-agent, multi-window collaboration with explicit ownership hand-off
worktree Isolated parallel work per task, auto-bound to the right branch
graph AST-scanned code dependency graph, exportable as Mermaid/DOT/ASCII
mcp A stdio Model Context Protocol server — plug straight into Cursor, Claude Desktop, and other MCP clients
stats Agent performance analytics — session length, throughput, exportable as Markdown/CSV
hooks Git post-commit auto-checkpointing, task-ID-prefixed commit messages
doctor Self-diagnosis for orphaned tasks, missing hooks, and DB drift
sync Push/pull state across machines when you need it — network access stays opt-in, never default

Shell Completions

Enable tab-completion for all commands and flags:

# Bash
carryctx completions bash >> ~/.bash_completion.d/carryctx

# Zsh (add to ~/.zshrc)
eval "$(carryctx completions zsh)"

# Fish
carryctx completions fish > ~/.config/fish/completions/carryctx.fish

# PowerShell
carryctx completions powershell | Out-String | Invoke-Expression

Git Hooks

Install CarryCtx git hooks to auto-checkpoint on commit and prefix commit messages with the active task ID:

carryctx hooks install       # install post-commit + prepare-commit-msg hooks
carryctx hooks status        # check which hooks are active
carryctx hooks uninstall     # remove CarryCtx hooks (restores .bak if present)

Diagnostics

carryctx doctor              # check project health (git, db, hooks, orphaned tasks)
carryctx doctor --json       # machine-readable output

Agent Skill Setup

Load the CarryCtx skill to give your coding agent first-class CarryCtx awareness:

npx skills add https://github.com/Xuepoo/carryctx-skills --skill carryctx

The skill teaches agents to manage sessions, tasks, progress, and checkpoints through CarryCtx — enabling persistent context across agent restarts and worktree switches.

Documentation

Principles

  • Local-first. No network access by default, no account, no telemetry. State lives in .git/carryctx/state.sqlite.
  • Agent-agnostic. Claude Code, OpenCode, Copilot, Codex, or a human — everyone reads and writes the same structured state.
  • Git is the source of truth for code; CarryCtx is the source of truth for intent. It never rewrites history or resolves merge conflicts for you.

License

MIT