cairn

Hand off work between AI agent sessions without re-explaining it.

When a Claude Code session stops (usage limit, account switch, /clear, tomorrow), the next session loses the reasoning: the goal, what was decided and why, what was tried and failed, and what comes next. Git keeps the code, not the reasoning. cairn keeps it.

• Save in one command. /cairn:handoff has the agent write a structured handoff while it still has the context. cairn validates it, blocks secrets, and attaches git facts.
• Resume with no command. A SessionStart hook injects the open handoff into the next session, together with a drift report of what changed since it was written.
• One handoff per task. Handoffs are keyed by ticket (PROJ-268), so parallel tasks in one workspace never overwrite each other.
• Worktrees and pipelines included. List them in the handoff; cairn records their branch and HEAD and warns when they moved or disappeared.
• Local and plain. Markdown files under ~/.cairn, mode 0600. No database, no LLM calls, no network except an optional gh lookup of pull requests; Python standard library only.

Status: 0.2.1, early release, used daily by its author. The file format and commands may still change before 1.0.

Contents

• Install
• Quick start
• Skills (inside Claude Code)
• Command reference
• The handoff format
• How it works
• Privacy and safety
• Configuration
• Uninstall
• Development

Install

Requirements: macOS or Linux, git 2.31+, python3 3.9+ (the one shipped with macOS works).

After installing the plugin, start a new Claude Code session. To try a local checkout instead, use claude plugin marketplace add /path/to/cairn, or link its bin/cairn into your PATH. Every route, npx included, runs the same Python code, so python3 3.9+ must be installed.

Quick start

1. Save. Near the end of a session, in Claude Code:

   /cairn:handoff
   

   or just say "save context", "running out of quota", "lưu ngữ cảnh". The agent replies with the handoff ID, for example saved 20261109-083012-proj-268.
2. Resume. Open a new session in the same project, on any account. The handoff is already in context; say "continue PROJ-268" and the agent summarises the goal, what is done and the next step.
3. Look around from a terminal:

   cairn list          # what is saved for this project
   cairn show PROJ-268 # the full handoff
   

Skills (inside Claude Code)

Both skills also trigger from plain language in English or Vietnamese ("handoff", "save context", "sắp hết quota"; "continue where we left off", "làm tiếp", "còn task nào đang dở").

Hooks run by themselves:

Command reference

Run cairn -h or cairn <command> -h for the same information in the terminal. A <ref> selects a handoff by task (any case), full ID, or a unique ID prefix of at least 4 characters; without one, cairn picks the newest handoff of the current branch, else the newest of the project. Commands that work with saved handoffs accept --dir DIR to act on another directory.

cairn save — store a handoff

Reads the body from stdin or --file, checks it, attaches the git state and saves it as open. Prints saved <id>. Saving again for the same task (or branch, without a task) replaces the previous handoff.

cairn template > handoff.md                    # start from the template and fill it in
cairn save --task PROJ-268 --file handoff.md   # then save it

cairn list — list handoffs

ID                        TASK      STATUS   AGE      TITLE
20261109-100105-proj-274  PROJ-274  resumed  40m ago  QC round 2 fixes
20261109-095106-proj-268  PROJ-268  open     50m ago  Checkout: bulk discount

cairn show [<ref>] — print a handoff file

cairn resume [<ref>] — continue a handoff

Prints the handoff with instructions for the agent and a drift report, then marks it resumed.

cairn rm <ref>... — delete handoffs

Asks delete N handoff(s)? [y/N] first. Pass --yes to skip the question; it is required when stdin is not a terminal. If any reference matches nothing, nothing is deleted.

cairn capture — show the git state cairn would attach

Current worktree (branch, upstream, HEAD, stashes, uncommitted paths, recent commits, pull requests) and a table of the other worktrees. Needs a git repository.

cairn template — print the body template

The sections agents fill in; Goal, Current state and Next steps are required.

cairn init — set up without the plugin

cairn prompt handoff|resume — instructions for any agent

Prints the skill instructions with the Claude Code specific parts removed, ready to paste into another agent.

cairn doctor — check the setup

One line per check (ok, warn, fail): Python, git ≥ 2.31, repository, Store writable, gh, plugin version, clipboard tool, cairn on PATH. Exits 1 if anything fails.

cairn hook <event> and cairn version

hook session-start|pre-compact|post-compact is what Claude Code runs; you do not call it yourself. version (or --version) prints the version.

Exit codes

The handoff format

# PROJ-268 Checkout: bulk discount

## Goal
Carts with more than 5 items get 10% off on Web and App. Done = e2e passes on both.

## Current state
API change merged in #633; App rounding fix open in #190.

## Next steps
- [ ] Address review comments on #190
- [ ] Run the price backfill on prod after deploy (dry run first)

## Decisions
- Discount lives in the pricing service, not the API layer: the App calls it too.

## Tried / didn't work
- Rounding in the API layer double-rounded prices; abandoned.

## Open questions
- Does the discount apply before or after tax?

## Key files
- services/pricing/discount.py

## Workspace
- worktree: .worktrees/proj-268-app
- pipeline: .pipeline/PROJ-268-e2e
- db: app_db_proj_268

Workspace lines labelled worktree (a git checkout) or pipeline (a folder) are recorded at save time and checked on resume; other labels are kept as written. Paths are relative to the project.

How it works

session A                                   session B (new account, new day, new worktree)
─────────                                   ─────────────────────────────────────────────
/cairn:handoff                              SessionStart hook
  └─ agent writes the body                    └─ cairn hook session-start
  └─ cairn save                                    ├─ newest open handoff of this project
       ├─ validate sections, block secrets        ├─ drift: new commits, moved worktrees
       ├─ capture git facts + Workspace           ├─ inject as additionalContext
       └─ ~/.cairn/<project>-<hash>/<id>.md       └─ mark it resumed

• Project: the main repository root, shared by all its worktrees. Outside git (for example a folder holding several repositories) the directory itself is the project.
• Store: ~/.cairn/<project>-<hash>/, one Markdown file per handoff. The hash keeps two folders with the same name apart.
• Drift: on resume cairn reports new or rewritten commits, a changed branch, uncommitted files that are still, newly or no longer modified, and each Workspace worktree or pipeline that moved or disappeared. Warnings make the agent wait for your go-ahead.
• Lifecycle: resuming never deletes; it marks the handoff resumed so it is not injected twice. Resumed handoffs are removed after 7 days and unclaimed ones after 30, the next time cairn writes. cairn rm deletes by hand.

Privacy and safety

• Everything stays on your machine. The only network call is optional: gh for pull request titles at save time (--no-gh to skip). The hooks never use the network.
• Files are 0600, directories 0700. No diffs or file contents are stored, only paths, branches, SHAs and commit subjects.
• Bodies containing likely secrets (private keys, AWS, GitHub, Slack, OpenAI, Anthropic keys, JWTs, password = ...) are rejected; the value is never printed.
• Hooks always exit 0 and report problems on stderr, so they cannot break a session.

Configuration

Uninstall

claude plugin uninstall cairn@sdc-ren   # the plugin
cairn init --uninstall                  # skills or AGENTS.md block installed by cairn init
pipx uninstall cairn-handoff              # the terminal command
rm -rf ~/.cairn                         # every saved handoff

Development

make setup     # Python 3.9 virtualenv with dev tools
make lint      # ruff, mypy --strict, duplicate and dead code, module size
make test      # pytest (make cov for coverage, make reqcov for requirement coverage)
make gen       # regenerate skills/ from src/agent_cairn/assets

The design is spec-driven: requirements, design decisions and the task plan live in docs/specs/ (Vietnamese), and code follows docs/CODING_STANDARDS.md. See CONTRIBUTING.md.

License

MIT