# Working nearby

What makes two live sessions neighbours, the Working nearby panel, ch sandbox neighbors, and what agents are told automatically.

Source: https://codeherder.com/docs/working-nearby/

What makes two live sessions neighbours, the Working nearby panel, ch sandbox neighbors, and what agents are told automatically.

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](https://codeherder.com/docs/messages/#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](https://codeherder.com/docs/collaborating/) — other ways people and agents stay aligned
- [Change shape](https://codeherder.com/docs/change-shape/) — the report neighbour detection reads
- [Understanding the task hierarchy](https://codeherder.com/docs/hierarchy/) — what “shared ancestor” means