Skip to content
peek
Esc
↑↓navigate↵open⌘Jpreview
On this page

Coordination

Advisory coord/check/claim signals for the shared things worktrees don't isolate.

Git worktrees already give each agent its own working directory, so file conflicts inside a single git-tracked checkout usually aren’t the problem. What worktrees don’t cover: a shared dev server, a database migration two agents both plan to run, a shared external resource, or a file that two agents in two different worktrees still both intend to touch. For that, peek has cooperative, advisory signals.

peek coord
peek coord . --writing
peek check src/core/engine.ts
peek claim src/core/engine.ts --ttl 2m --as codex-main
peek release <claim-id> --claim-id --json

Useful details

  • peek coord . --writing shows active writers and file claims, hiding idle noise.
  • peek list --files gives the same file-context view as part of a regular session list.
  • peek check <file> exits 0 when clear and 1 on conflict. Running a script is reading it; only a command’s real targets (redirects, tee/touch/rm operands, cp/mv destinations, sed -i files) count as writes, and a path scraped from a command counts only when it exists on disk.
  • peek check --files-from changed-files.txt bulk-checks a planned edit; --files-from - reads stdin. A space-separated line that names no file is split into paths, and entries not on disk are named on stderr.
  • peek check ignores your own claims by default. --include-self shows them, --ignore-self also drops your own session’s writes, --as <owner> covers a claim made under another name, and --ignore-session <name|id> names a session outright.
  • peek claim <file> --ttl 2m broadcasts temporary write intent (2m is the default TTL if you omit --ttl). Claiming the same files again renews the record instead of stacking a second one.
  • peek release <claim-id> --claim-id --files-from done-files.txt partially releases a claim.
  • peek coord . --since-file .peek-cursor --json --fields currentTask,intent,activeWritingFiles is the polling-friendly JSON path.

Who you are

check and claim need to know which session is yours. The rule, in order:

  1. CLAUDE_SESSION_ID, when the harness sets it.
  2. The one live top-level session whose cwd is this directory.
  3. Otherwise an anonymous owner made of user, host and directory.

When several live sessions share the directory (two agents reviewing one repo), peek does not guess. It says which sessions it could not choose between, uses the anonymous owner, and tells you to set CLAUDE_SESSION_ID or pass --as <name>. A claim made with --as still records who made it, so your own check recognises it either way.

The check-then-claim pattern

peek check src/core/engine.ts        # exit 1 if another active agent is writing it
peek claim src/core/engine.ts --ttl 10m   # default TTL is 2m — often too short for long edits
# ... make your edits ...
peek release src/core/engine.ts      # drop the claim when done

Set an explicit --ttl on claim: the 2m default expires mid-work on longer edits.

Was this page helpful?