Your AI agent stopped. The next one picks up exactly where it left off.
PCS is a local-first command line tool and MCP server that hands work from one AI coding agent to the next. When an agent hits a token limit, you start a new chat, or you switch from Claude to Cursor, PCS rebuilds what actually happened in the project from git and recorded evidence, and gives the next agent a brief it can trust.
Never trust an agent's "done". PCS keeps what it saw itself apart from what an agent claimed.
Agents lose context when a session ends. The usual fix is a summary written by the agent that just ran out of room, which is exactly the part you cannot trust: it may say tests pass when they never ran, or forget the file it was halfway through editing.
PCS records facts with their source, so the next agent knows which lines are solid:
| Level | Meaning | Example |
|---|---|---|
verified |
PCS observed it itself | git state, file hashes, a test run PCS executed with its exit code |
reported |
A person or agent claimed it | "task done", "next step is X" |
inferred |
Derived from other facts | "the session was interrupted" |
A task counts as verified only when a passing test run that PCS executed is linked to it, and only while the code still matches the state that run saw.
You need Node.js 22.13 or newer and git.
npm install -g pcskit
cd your-repo
pcs init
Connect the agents you use (one command each, --remove undoes it):
pcs connect claude-desktop
pcs connect cursor
pcs connect claude-code
Tell agents how to use PCS, and for Claude Code let hooks do it automatically:
pcs agents install # adds a marked block to CLAUDE.md, AGENTS.md, .cursor/rules
pcs hooks install # Claude Code: sessions start, checkpoint and end by themselves
Check that everything is in place:
pcs doctor
Details for each app: docs/CLIENTS.md.
pcs session start --agent claude
pcs note add task "Add the --json flag to the exporter"
pcs test --task <task-id> -- npm test # PCS runs it and records the result
pcs note add next "Wire the flag in src/cli/export.ts, then update the tests"
pcs session end --reason limit
pcs handoff # writes .pcs/HANDOFF.md
The next agent, in any tool:
pcs resume --agent cursor
Resume checks the handoff against the evidence log, snapshots the repo, warns if the code moved since the handoff, and prints the brief. Every line carries its level: [verified], [reported by claude] or [inferred]. With MCP connected, agents call pcs_resume and pcs_handoff themselves. No agent running? pcs resume --prompt prints a ready-to-paste takeover prompt.
If an agent died before writing a handoff, PCS builds one from the evidence log and marks the interrupted session as inferred.
- Handoffs you can trust. Original task, completed work (verified, passing-but-code-changed, or reported only), work in progress, files touched, test results with the output of failing runs, open problems, next steps and do-not-touch notes.
- Tamper-evident history. Events are stored in an append-only SHA-256 hash chain.
pcs verifydetects edits, deletions and reordering. A signed anchor kept outside the project also detects truncation and rewrites. - Audit export.
pcs exportwrites the log as JSON or Markdown that can be checked without PCS. - Secrets stay out. Redaction runs before anything is stored. Files flagged sensitive (keys,
.env) are listed by name and never read. - Works with your agents. MCP server for any MCP client, Claude Code hooks, and instruction blocks for CLAUDE.md, AGENTS.md and Cursor rules.
- Always on, if you want. A background watcher snapshots the repo as files change and flags stalled sessions;
pcs autostart installstarts it at login. - Many repos.
pcs workspacelists all your projects; each keeps its own log. - Read-only dashboard.
pcs dashboardshows sessions, tasks with their evidence, notes, test runs and the event timeline on 127.0.0.1.
| Area | Commands |
|---|---|
| Setup | init, doctor [--fix], deinit, config show|init, connect, agents install|uninstall, hooks install|uninstall|status, autostart install|uninstall|status |
| Work | session start|end|current|list, task add|list|update, note add|list|resolve, snapshot [take|list|diff], test -- <command>, evidence list|show|link |
| Handoff | handoff, resume [--prompt], status, watch |
| Trust | verify [--anchor], anchor, log, export |
| Many projects | workspace add|remove|list, dashboard [--workspace], mcp [--workspace] |
Run pcs <command> --help for options. Several commands accept --json for scripts.
Start the server with pcs mcp (or let pcs connect write the config). Tools: pcs_status, pcs_verify, pcs_resume, pcs_handoff, pcs_session_start, pcs_session_end, pcs_snapshot, pcs_task_add, pcs_task_list, pcs_task_update, pcs_note_add, pcs_note_list, pcs_note_resolve, pcs_evidence_list, pcs_workspace_status. Agents should start with pcs_resume.
--read-onlyexposes only tools that cannot change anything.pcs_test, which runs a command on your machine, is off unless you pass--allow-test.- Recorded content is returned as data, with control characters stripped, and the server instructions tell the model not to follow it.
PCS reads repositories and agent output that it does not trust, so it is built defensively.
- Local only: no network access and no telemetry. Data lives in
.pcs/inside your project, git-excluded and owner-only (POSIX modes, Windows ACLs). - Git is run read-only with a hardened adapter: no repo-defined commands, no optional locks, timeouts, validated hashes.
- Commands are argument arrays, never shell strings.
pcs testcan be limited to an allowlist. - Untrusted text is sanitized before it reaches the terminal, markdown or the dashboard.
- Policy files can only tighten defaults. The global file is the trusted one, because a project file can be edited by an agent.
Honest limits: the hash chain proves changes only if you keep the anchor or an export somewhere else; redaction is pattern based, so add your own rules for your secrets; and reported claims are labelled, not proven. Full reasoning is in docs/DECISIONS.md. To report a vulnerability, see SECURITY.md.
Tested in CI on Linux, Windows and macOS with Node 22 and 24, including git worktrees and submodules, concurrent writers and fuzzed input.
pcs deinit removes everything PCS added to a project: the .pcs folder, hooks, instruction blocks and the login entry. pcs connect <app> --remove removes the MCP entry.
Issues and pull requests are welcome. Start with CONTRIBUTING.md; everyone is expected to follow the code of conduct. Rules for AI agents working on this repository are in AGENTS.md. Changes are listed in CHANGELOG.md.
Apache-2.0. See LICENSE.