Skip to content

v0.1.0 · Local-first · Apache-2.0

Your AI agent stopped. The next one picks up exactly where it left off.

PCS is a local-first CLI and MCP server that hands work from one AI coding agent to the next. It rebuilds what actually happened from git and recorded evidence, and never takes an agent’s “done” on trust.

npm install -g @knihal/pcskit
  • verifiedPCS observed it itself
  • reportedA person or agent claimed it
  • inferredDerived from other facts
.pcs/HANDOFF.mdexample

Completed

  • verifiedAdd the --json flag to the exporterpassing run #14 (npm test, exit 0), code unchanged since
  • reported by claudeUpdate the export docsno test run linked

Open problems

  • inferredSession ended without a handoffinterrupted at the token limit

Next

  • reported by claudeWire the flag in src/cli/export.ts, then update the tests

Do not touch

  • verified.envflagged sensitive: listed by name, never read

The problem

The summary you get is written by the agent that just ran out of room.

That 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.

What the agent wrote

“All tests pass. The exporter is done. Only the docs are left.”

Confident, unchecked, and gone with the session.

What PCS recorded

  • reported by claudeExporter is done
  • verifiedLast test run exited 1 (PCS ran it)
  • verifiedsrc/cli/export.ts changed after that run
  • inferredSession was interrupted

The evidence model

Never trust an agent’s “done”. Keep the source of every fact.

PCS records each fact with where it came from, so the next agent knows which lines are solid.

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.

A handoff, step by step

From a dead session to a trusted brief in one command.

  1. Work as usual

    Agents connect over MCP, or Claude Code hooks start and end sessions for you.

  2. PCS records evidence

    Sessions, snapshots from git, and test runs PCS executes itself, in a hash-chained log.

  3. The session ends

    Token limit, new chat or a switch of tools. PCS writes the handoff, or rebuilds it from the log if the agent died first.

  4. The next agent resumes

    Resume checks the handoff against the evidence, warns if the code moved, and prints a brief where every line carries its level.

Agent A: hits its limit
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 the command and records exit code, duration and output
pcs note add next "Wire the flag in src/cli/export.ts"
pcs session end --reason limit
pcs handoff
wrote .pcs/HANDOFF.md
Agent B: picks up, in any tool
pcs resume --agent cursor
handoff checked against the evidence log
code unchanged since the handoffverified
Done: Add the --json flag to the exporterverified
Next: Wire the flag in src/cli/export.tsreported by claude
Output abbreviated. With MCP connected, agents call pcs_resume and pcs_handoff themselves.

Tamper-evident history

Try to rewrite the past. PCS notices.

Events are stored in an append-only SHA-256 hash chain. pcs verify detects edits, deletions and reordering. A signed anchor kept outside the project also detects truncation and a full rewrite.

Real SHA-256, computed in your browser.
  1. #1session.startedagent: claudeverifiedhash ········
  2. #2task.addedAdd the --json flagreportedhash ········
  3. #3test.runnpm test, exit 1verifiedhash ········
  4. #4note.addednext: fix the failing testreportedhash ········
  5. #5session.endedreason: limitverifiedhash ········
pcs verify
log intact: 5 events, chain verifiedexit 0

What you get

Built like infrastructure, runs like a utility.

Handoffs you can trust

Original task, completed work, work in progress, files touched, test results with the output of failing runs, open problems, next steps and do-not-touch notes.

Audit export

pcs export writes the log as JSON or Markdown that can be checked without PCS.

Secrets stay out

Redaction runs before anything is stored. Files flagged sensitive, such as keys and .env, are listed by name and never read.

Works with your agents

An 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 starts it at login.

Many repos

pcs workspace lists all your projects. Each keeps its own log, so one repo never affects another.

Read-only dashboard

Sessions, tasks with their evidence, notes, test runs and the event timeline, served on 127.0.0.1 only.

No network, no telemetry

Everything lives in a git-excluded, owner-only .pcs folder inside your project.

Works with your agents

One command per app. --remove undoes it.

pcs connect writes the PCS MCP server into the app's config. It keeps your other servers and never overwrites a file it cannot parse.

Claude Desktop

pcs connect claude-desktop

Quit the app fully and reopen it.

Cursor

pcs connect cursor

Per project, or --global for all projects.

Claude Code

pcs connect claude-code

Add pcs hooks install so sessions start and end by themselves.

Full connection guide →

Security model

Built defensively, because it reads text it does not trust.

Repositories and agent output are untrusted input. PCS treats them that way.

  • 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 runs read-only through a hardened adapter: no repo-defined commands, timeouts, validated hashes.
  • Commands are argument arrays, never shell strings. pcs test can 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.

The next agent should never start from zero.

Install PCS, run pcs init in your repo, and connect an agent.

npm install -g @knihal/pcskit