Peers

---
name: peers
description: Lists every live Claude Code session on this machine, in every account (each config dir, twins included), with its project, title, state and the `uds:` address to message it. Use it whenever you need to message, check on or coordinate with another session, especially one in a different account, since ListAgents only shows the current account. Triggers on "peers", "which sessions are running", "list the sessions", "what is <session name> doing", "message the orchestrator", "send this to lane 2", "find the address of", "who is still running", or before any SendMessage to a session you have not listed yet in this turn.
allowed-tools:
  - Bash
---

# Peers

ListAgents shows only the sessions of the account this one runs in, yet SendMessage to a
`uds:<socket>` address reaches a session in any account. This skill lists them all.

The script: `${CLAUDE_PLUGIN_ROOT}/skills/peers/scripts/peers.py`

## Run it

```bash
python3 -I "${CLAUDE_PLUGIN_ROOT}/skills/peers/scripts/peers.py" [filter words]
```

- Filter words narrow the list (all must match the title, project or account), e.g. `lane 2b`.
- `--json` prints the rows as JSON (account, project, cwd, title, state, address, sessionId, pid, self, context, reports) for scripts and other skills. `context` is `{used, window, percent, flag, source}` (`source` is `session` for the harness's own number or `estimate`) or null before a session's first reply.
- In a project with several orca fleets the plain list is **grouped**: the Admiral and shared checkers, then each fleet (orchestrator first, lanes by number), then every other session; `--flat` prints it ungrouped. JSON rows also carry `fleet` and `fleetRole` (`admiral`, `fleet` or null).
- `reports` is `{kind, name, address, session, fleet, updatedAt}` when the session recorded a reporting line (`kind` is `orchestrator`, `parent`, `independent` or `admiral`; see orca-fleet's `join-lane`), else null. `fleet` is set when the project runs several fleets. The row then ends with `reports: <kind> <name>`, plus `fleet: <id>` when set.
- It reads only. It never writes to a Claude Code config dir.

Show the result to the user as a short list. Mark which row is this session (the script adds
"(this session)"), and never message that row.

## Messaging from the list

Call SendMessage with `to` set to the address exactly as printed (`uds:/tmp/cc-socks/<pid>.sock`).

- **Re-list before you send if the list is more than a few minutes old.** An address belongs to a
  process. When a session moves to another account, restarts or resumes, it gets a new pid and a
  new address, and the old one is dead.
- A session in a different permission mode may hold your message for its user's approval, so a
  successful send is delivery, not agreement. Do not treat silence as a yes.
- When you give another session your own address, take it from this list ("this session") at
  that moment, for the same reason.

## States

`busy` working, `waiting` blocked on its user (a question or a permission prompt), `idle`
finished its turn, `shell` turn finished while a background shell still runs. A session that is
waiting on its user will not read your message until the user answers it.

## Context use

The percent column is how full each session's context window is. A plain number (`16%`) is the
session's own reading: the orca-peers hooks module saves what Claude Code measured to
`~/.config/orca-strator/context/<sessionId>.json` on every change. A number with a tilde (`~16%`)
is an estimate from the transcript, used only when that file is missing (the session runs without
the module, for example an older orca-peers): it assumes a 1M window unless `context_window:` in
`~/.config/orca-strator/config.yaml` says otherwise, and it never carries a flag. At 70% a measured
row adds `PREPARE HANDOVER`, at 85% `HAND OVER`. When you report the list, name the sessions with
a flag first: a flagged session should write its handover note soon. `·` means no reply yet. Never
order a handover on an estimate; ask the session for its own `/context` reading instead.

## When the list looks wrong

- **An account is missing:** the script finds `~/.claude` and every `~/.claude-<name>` that has a
  `sessions/` folder. For other locations, or to name the accounts, set `accounts_file` in
  `~/.config/orca-strator/config.yaml` (see the README).
- **A title says "untitled" or a folder name:** the session has no name and no title yet. Its
  project and address are still right.
- **"No live Claude Code session found"** while sessions are open: the record format may have
  changed in a new Claude Code version. Say so, and fall back to ListAgents for this account.