boxel: Skill for Claude Code

Agent Peer Collaboration

Several Claude sessions routinely run at once on this machine, each in its own worktree of the same repo, sharing one test stack, one Postgres test lane, one set of Docker containers, one .git directory, and one GitHub API budget. Their work collides and corroborates constantly, and none of them can see another's transcript. An agent that stays silent turns the human into the router for information the agents could have exchanged directly — and the human only learns of the overlap if they happen to notice.

ListAgents also reaches sessions outside this machine — the same account's sessions on other machines (over Remote Control) and in the cloud, each row labelled by kind. Those peers share the repo, the PR set and the GitHub API budget, but none of the local machinery: their :4200, their Docker, their test lane and their .git are not yours. So there are two scopes, and each protocol below says which one it belongs to. Running a same-machine protocol against a peer elsewhere does worse than add noise: it produces false all-clears on resources that peer never held.

So: coordinate proactively, without being asked. The rest of this skill is when, how, and the shared-resource protocols that make it work.

Tools

• ListAgents — who is live right now, each row labelled by kind: subagents you spawned, other sessions on this machine, and — when Remote Control is connected in your session — the same account's sessions on other machines and in the cloud. Names are the address. A session without Remote Control is invisible here, so the listing is a floor on who is live, never a roster: absence proves nothing about another machine.
• SendMessage({to: "<name>", message: "..."}) — message a peer. The bare name delivers to exactly one live session wherever it runs; append the [ref] a listing or an error shows only when the name is ambiguous, which it will be across machines that name worktrees alike. Two delivery asymmetries matter. A peer on this machine reports back (a [Cross-session delivery notice]) when it refuses or holds your message, while a Remote Control or cloud peer reports nothing at all — so for a remote peer, silence carries no information in either direction. And notify_when_idle: true — the way to wait on a holder without polling — subscribes only to a session on this machine.
• Ownership of a running thing: lsof -nP -iTCP:<port> -sTCP:LISTEN names the listener and its pid, lsof -a -p <pid> -d cwd -Fn | sed -n 's/^n//p' names the worktree that launched it, and ps -ww -o command= -p <pid> recovers the invocation it was started with. Those three behave the same on macOS and Linux, and lsof exits 1 when nothing matches, so it chains like any other guard. On Linux ss -ltnpH "sport = :<port>", readlink /proc/<pid>/cwd and /proc/<pid>/cmdline are equivalent and cheaper; neither ss nor /proc exists on macOS. Worktree and session names are the cheap tell for who that is.
• A missing probe fails open, which is the dangerous direction for every check below: the command is not found, the pipeline prints nothing, and an in-use resource reads as clear. ss and /proc are absent on macOS, lsof is absent from slim Linux images. Make the tool's own presence part of the test (command -v lsof) and treat "not found" as busy, never as free.