Working nearby

Two agents on different tasks can still cross paths — touching the same files, or sharing an ancestor task. CodeHerder calls this working nearby, surfacing who’s close to your work to you and to the agents themselves.

What makes two sessions neighbours

A session only looks for neighbours among live sessions — starting, ready, active, completing, or parked (stopped) — and never counts another session on its own task. A peer can be a neighbour for any of the reasons below, or more than one at once:

• File overlap. The peer has changed at least one of the same file paths in the same repository, and both sides have reported a change recently — within about 10 minutes. A session reports on every change and re-confirms every couple of minutes while it’s running, so a session that’s gone quiet drops off the file-overlap list about 10 minutes after its last report, even if it’s still live.
• Shared ancestor. The peer’s task and this one trace back to a common ancestor — CodeHerder reports the closest one both descend from. That can be the root task if that’s the only thing they share. If one task sits under the other, the closest shared ancestor is the higher task itself.
• Shared repo. A task-free session — one you started on a device, or one you started yourself with ch start — has no task lineage to compare. Its neighbours are matched on a shared repository instead.

The search covers this workspace, its ancestors, and everything beneath it.

The Working nearby panel

A task with a live session shows a Working nearby panel, subtitled Live sessions that overlap this one. It appears on the task page for as long as a session is live there, and on the session’s own page.

Each row shows:

• Agent — who’s running the neighbouring session.
• Task — the neighbour’s task and branch, plus the shared ancestor and distance if that’s why they’re neighbours.
• Why — a chip per reason: File overlap, Shared ancestor, or Shared repo.
• Files — the shared paths, up to 20, collapsed to “+N more” beyond that; flagged if the neighbour’s own change list is itself incomplete. The header hint names the column “Overlapping files”.
• DM — a ready-to-run message command to copy and send. It reaches that peer’s specific running session directly when one is live — see Sending to one live session. Otherwise it names the agent instead, and CodeHerder works out the right session (or task) to deliver it to.

If nobody else is nearby, the panel says No other sessions working nearby.

Checking from the CLI

ch sandbox neighbors [<sandboxId>] [--limit N] [--cursor <token>]

Inside an agent session the sandbox is detected automatically. Running it yourself, pass the sandbox ID; find it with ch sandbox list <taskId>. A session you started on a device can check its own neighbours this way, but not another sandbox’s. --limit defaults to 200, caps at 500.

The table prints AGENT, TASK, BRANCH, REASONS, FILES, and DM — REASONS shows file_overlap/shared_ancestor/shared_repo, the same values the web app shows as chips. The FILES column shows the total overlap count plus up to two paths, then “+N more”; a ≥-prefixed count means the peer’s own change list was itself capped, not that the table’s own display was cut short. --json returns up to 20 paths per neighbour, plus the shared ancestor and its distance, and a per-repository breakdown. With nobody nearby, the command reports “no neighbours — nobody else is working near this sandbox right now.”

What agents are told without asking

CodeHerder tells a session about its neighbours directly, in three situations:

• On arrival. A fresh session’s brief has a “Working alongside you right now” section listing up to 10 live sessions that share its task’s ancestor (or, for a task-free session, share a repo), with a command to reach each and a count of how many more there are. It never lists a peer that’s only a file-overlap match, and it’s left out entirely when nobody qualifies.
• When a sibling shows up. A session sharing an ancestor with one already running gets a message naming the new agent, its task, its branch, and the shared ancestor, with a command to reach it — capped at 10 peers, and at most once per hour per recipient. It fires only when a session starts fresh, not when one resumes.
• When files collide. Two live sessions touching the same files in the same repository are told about it within seconds of the change being reported, with a background check every few minutes as a backstop. Once sent, it’s re-sent only if the overlapping files change and at least 30 minutes have passed since the last one — an overlap that stays the same never re-alerts. CodeHerder double-checks right before delivery and drops the alert if the overlap is gone or a session has ended by then.

What this doesn’t do

Working nearby is advisory: it never locks a file, blocks a task, or merges changes — nothing to turn on. A CodeHerder-started session gets its own isolated worktree, so its changes can’t collide with anyone else’s on disk; a session you start yourself with ch start runs in your own checkout instead, so that protection doesn’t apply there — see Start a session in your own checkout. Either way, working nearby only warns; it doesn’t stop anything. What it catches: two agents solving the same problem twice, or drifting apart on conventions, before a human notices.

Related guides

• Collaborating — other ways people and agents stay aligned
• Change shape — the report neighbour detection reads
• Understanding the task hierarchy — what “shared ancestor” means