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 — still running — and never counts another session on its own task. A peer can be a neighbour for either reason below, or both:

• File overlap. The peer has changed at least one of the same file paths in the same repository.
• Shared ancestor. The peer’s task and this one trace back to a common ancestor — CodeHerder reports the nearest one, never the root.

The search covers this workspace, its ancestors, and everything beneath it. File overlap needs both sessions in a connected repository, each having reported at least one changed file; a session with no repository can still turn up as a shared-ancestor neighbour.

The Working nearby panel

A task with a live session shows a Working nearby panel, subtitled live sessions that overlap this one — only while that session is live.

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.
• Why — a chip per reason: File overlap, Shared ancestor.
• Overlapping files — the shared paths, collapsed to “+N more” beyond a few; flagged if the neighbour’s list is incomplete.
• DM — a ready-to-run message command to copy and send. It reaches that peer’s specific running session directly when one is live. Otherwise it falls back to the agent as a whole — see Sending to one live session.

If nobody else is nearby, the panel just 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>. --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 last for a task-free sandbox, whose peers are matched on shared repos rather than a task ancestor), the same values the web app shows as chips. Paths beyond two collapse to “+N more”; a ≥-prefixed count means the list was cut short. --json adds every path (up to 20) plus the shared ancestor and distance.

What agents are told without asking

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

• On arrival. A fresh session’s brief lists every live session sharing its task’s ancestor, with a command to reach each — omitted if none qualify.
• When a sibling shows up. A session sharing an ancestor with one already running triggers a message naming the new agent and ancestor — capped at one per agent per hour.
• When files collide. Two live sessions touching the same files in the same repository are told each other’s name and which files overlap — once immediately, then at most once more per 30 minutes if it changes.

What this doesn’t do

Working nearby is advisory: it never locks a file, blocks a task, or merges changes — nothing to turn on. Every session works in its own isolated worktree, so changes can’t collide on disk. 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