Make it automatic

MCP gives an agent tools; a skill gives it behavior. Install the ctxfile behavior pack once and any agent, while doing its normal work, knows when to checkpoint context and how to do it well. You stop prompting “save this”; when you switch providers, the data is simply already there. Prompting remains as a manual override.

Install

ctxfile init

init asks for consent first (auto-capture is an explicit choice, never a default you discover later), then detects your harnesses and installs the behavior file where each one looks:

All five renders come from one canonical spec in the package (behaviors/canonical.md); community PRs for new harnesses are markdown, the same cheap-connector dynamic as the ingest prompt snippets.

What the skill teaches the agent

• Session start: call get_context, resume the matching thread, and say so in one line.
• Checkpoint on significance, not on time: a task completes, a decision with rationale is made, the user says goodbye or mentions switching tools, or ~30 minutes of substantive work pass. Never on trivial exchanges or unchanged state.
• Handoff detection: “hand this off” or “I'll continue on my phone” produces the full enforced handoff package.
• Visibility, non-negotiable: every automatic save is announced: ✓ Checkpointed to ctxfile (thread: Q3 campaign). Never silent.
• Thread hygiene: distinct work gets a distinct thread; when uncertain, ask once.
• The CLI, on request only: agents with a shell learn the admin commands (pause, threads private, ingest list/rm, export, sync) and run them only when you explicitly ask, stating the command; they never touch vault setup or your passphrase.

The guardrails (server-enforced, not just requested)

Automatic checkpoints carry trigger: "auto" provenance, and the server holds the line even if an agent misbehaves:

• ctxfile pause refuses every automatic checkpoint until ctxfile resume; manual saves keep working.
• ctxfile threads private <id> excludes one thread from auto-capture entirely (--off to include it again).
• Debounce: an unchanged checkpoint on the same thread inside the window (default 5 minutes, behavior.debounceMinutes in config) is skipped; materially different content and handoffs always land. No garbage checkpoints.
• Everything lands in the same reviewable store: ctxfile ingest list shows auto captures identically, labeled auto checkpoint, and ingest rm deletes them.

A silent ambient recorder would contradict the entire trust story; a narrated one reinforces it. That is why the announcement line is a behavior rule AND baked into the tool's response text.

Try the loop

ctxfile init --yes
# work in Claude Code / Cursor as normal; when a task completes you'll see:
#   ✓ Checkpointed to ctxfile (thread: <your work>)
ctxfile threads          # it's there
ctxfile pause            # and now it isn't captured, until:
ctxfile resume