Recording an Arc

An Arc is one unit of work: everything between patcharc start and patcharc stop. It can span many commits, a rebase, several branches, and more than one worktree. The recording is local; nothing is sent anywhere until you choose to share.

Starting

$ patcharc start --detach "Add invitations to organisations"

• Goal: the argument. It is the first section of the review and the title of the capsule.
• --detach: spawns patcharc __observer as a detached process (its own process group), with output appended to .patcharc/observer.log and its PID in .patcharc/observer.pid. Use it for anything longer than a few seconds.
• Foreground (no --detach): runs the observer for 1.5 seconds and returns. Commits made after that are not recorded by that run.

Only one Arc is active per repository. start while an Arc is active returns an error; stop it first.

What the observer records

Every 1.5 seconds the observer runs Git plumbing and records:

• New commits reachable from HEAD: SHA, author, timestamp, message, parents.
• The files each commit touched, with status and line counts.
• Branch and worktree identity, so an Arc that moves between worktrees stays one Arc.

It reads only. It installs no hooks, touches no refs, and never modifies your working tree. If you amend or rebase, the new commits are observed like any other; the capsule keeps the commit evidence as Git produced it.

What the observer does not record in 0.2.0

• Test runs. There is no test-output parsing yet, so the review's Verification section shows zeros unless you record results yourself in a note.
• Agent transcripts. Commits made by Claude Code, Codex, Cursor, or any other tool are recorded as commits; the conversation that produced them is not captured. See Working with AI coding agents.
• Uncommitted changes. Only commits are evidence. patcharc checkpoint records the current HEAD, not the dirty tree.

Notes, decisions, risks

$ patcharc note "Switched to WAL mode; lock contention disappeared"
$ patcharc decision "Keep SQLite for now; revisit at 50k sessions"
$ patcharc risk "Migration on existing databases is untested"

All three take the text as arguments (quote it) and attach it to the active Arc with a timestamp. They appear in the review: decisions and risks in section six, notes alongside. Record them when you make the call, not at the end; the timestamps are part of the story.

Checkpoints

$ patcharc checkpoint "schema migrated, before data backfill"
✓ Checkpoint #2 recorded

A checkpoint pins the current HEAD with a label. In 0.2.0 it records the commit, not a snapshot of the working tree, and it does not inspect whether the tree is clean.

Status

$ patcharc status
Arc arc_8f2c1d4a9b (active)
  goal:        Add invitations to organisations
  branch:      feat/invites
  head before: a1b2c3d
  commits:     7
  files:       23
  redactions:  0

With no active Arc, status prints No active Arc. Run patcharc start [goal]. and exits 0.

Stopping

$ patcharc stop

stop stops the detached observer, computes the review, and seals the capsule to .patcharc/capsules/<arc_id>.parc. --share adds a line reminding you how to share; it does not upload. If the observer process died earlier (for example, a reboot), stop still seals what was recorded up to that point.

Scopes

If the repository is a monorepo, the review groups changes by scope (package, service, module). Detection is automatic for ten workspace layouts, or you declare scopes in config.yaml. See Monorepo scopes.

Practical patterns

• One Arc per pull request. Start when you branch, stop when you open the PR, paste the ArcLink in the description.
• Long-running work. Arcs can last days. The observer is a lightweight poll; leave it running, or stop and start a new Arc per phase.
• Pairing with an agent. Start the Arc, let the agent commit, record your decisions and risks as you review its work, stop when you hand off.