Skip to content

Cross-pane activity ledger

When several agents share one working tree, they edit files unaware of each other and can clobber each other's uncommitted work. The activity ledger is a best-effort, pull-only awareness surface: a background poller records which pane last touched which file in each git tree, so you (or your agents) can spot overlaps before they become conflicts.

  • What it records. Per git tree, in a .vupai/ directory at the tree root: activity.current.json (latest state per pane) plus activity.jsonl (history). Each entry names the pane, the files it touched, a coverage flag (exact when a tool edit-marker proves the pane wrote the file, git-delta when only scrollback ties it, or churn-only for an active pane no file could be pinned on), and any contended_with panes editing the same file. .vupai/ is auto-gitignored, so it never appears in git status.
  • How it decides. git status provides what changed; each pane's scrollback provides which pane; their intersection is the attribution. A tool edit-marker (e.g. Claude's Update(<path>)) counts as proof a pane wrote that file and outranks a bare path mention, so a pane that merely discussed a file is not credited as its editor (and you don't get phantom conflicts from panes that just talked about it). It is post-write on a ~2s poll, so it reduces clobbering by surfacing overlaps; it does not prevent a sub-2-second race, and it never blocks or injects into a pane.
  • Read it.
    • vupai activity shows the current ledger, grouped by tree.
    • vupai activity --stats reports contention and attribution rates (use these to judge whether it earns its keep in your workflow).
    • Say "activity" (or "who's editing") to hear the digest.

Let your agents use it

The ledger is pull-only by design, so nothing forces an agent to read it. If you want your agents to coordinate through it, tell them to: add a few lines to your project's AGENTS.md (or CLAUDE.md, or whatever instructions file your agent loads):

## Before editing a shared file
This repo may have several agents working in sibling panes at once. Before you
edit a file, read `.vupai/activity.current.json` at the repo root. If another
pane is listed as touching that file, or the file appears under a pane's
`contended_with`, stop and coordinate or pick different work instead of
overwriting it (the sibling's edits are uncommitted and you would clobber them).
A pane with coverage `churn-only` is active but its file is unknown: treat the
tree as contended and be cautious.

This is opt-in and best-effort: an agent consults the ledger only if its instructions tell it to, and even then it will not monitor the file continuously on its own. For a hard guarantee, give each agent its own git worktree (a planned opt-in) so panes physically cannot clobber one another.

To see the uncommitted changes the ledger attributes, open the live review.