--- name: coord description: "Talk to the ClaudeTools coordination API without re-deriving the schema: send/read inter-session messages or fleet broadcasts, coord todos, claim/release locks, coord status. Triggers: send a coord message, broadcast to the fleet, coord todo, claim a lock, coord status." --- # coord — coordination API helper One command for the coord API. The script auto-derives everything machine-specific from `identity.json` (the API base `coord_api`, this session id `/claude-main`, and the `user`/`machine` for attribution) and bakes in the fleet conventions, so you never hand-build the JSON again. ``` bash "$CLAUDETOOLS_ROOT/.claude/scripts/py.sh" "$CLAUDETOOLS_ROOT/.claude/skills/coord/scripts/coord.py" ... ``` | Command | What it does | |---|---| | `status` | Coord status (locks, components, workflows). | | `msg send "" ""` | Send a message. `` = `ALL` (broadcast), a machine name (`HOWARD-HOME`), or a full session id (`HOWARD-HOME/claude-main`). | | `msg send "" --body-file ` | Same, body from a file (use for long/multi-line bodies — avoids shell-quoting breakage). | | `msg inbox [--all]` | Your unread messages (or `--all`). Print these prominently per the coord rule. | | `msg read ` | Mark a message read. | | `msg purge --before YYYY-MM-DD [--to ] [--yes]` | Delete dealt-with messages older than the cutoff date. **DRY-RUN by default** (previews what would go); add `--yes` to actually delete. `--to` scopes to one recipient session. Refuses to run without `--before` (can't wipe the store by accident). Destructive + fleet-wide — coordination msgs are ephemeral; the durable record is in session logs. | | `todo add "" [--user U] [--project KEY] [--parent ID] [--source TXT] [--auto]` | Create a todo (auto-fills `created_by_user`/`created_by_machine`). `--text-file` for long text. | | `todo list [--user U] [--project KEY] [--status pending\|done\|all]` | List todos. | | `todo done ` | Mark a todo done (sets `completed_by`). | | `lock claim "" [--ttl HOURS]` | Claim a work lock (default ttl 2h). | | `lock release ` | Release a lock. | | `lock list [--project KEY]` | List active locks. | | `component set [--version V] [--notes TXT]` | Update a component's deploy state (auto-fills `updated_by`). E.g. `component set gururmm dashboard deployed --version 0.2.39`. | ## Conventions it handles for you - **Broadcast = `to_session: "ALL_SESSIONS"`** (NOT an omitted/`null` target — that does not reach sessions). Just pass `ALL`/`fleet`/`broadcast` as ``. - **Session id = `/claude-main`.** Passing a bare machine name to `msg send` expands to that; passing `user`/anything with `/` is used verbatim. - **Attribution auto-filled** from identity.json (`created_by_user`, `created_by_machine`, `from_session`, lock `session_id`). - **Long bodies via `--body-file`/`--text-file`** (the same lesson as grok `--prompt-file`: don't fight shell quoting for multi-line content). ## How delivery works (important) - A **message** is surfaced to the target session(s) by the session-start hook as "UNREAD COORD MESSAGES" — i.e. it reaches a machine the next time a Claude session starts there. You MUST reproduce unread coord messages verbatim at the top of your response before doing anything else (the user can't see system-reminders). - **Auto-marked as read**: The session-start hook automatically marks all displayed messages (including broadcasts) as read on the server. Once shown, they won't re-appear in future sessions. - A **todo** is durable and queryable until marked done — use it as a backstop for fleet rollouts (a message can be read-and-forgotten; a todo persists). - Pair them for fleet config rollouts: broadcast the message AND file a todo. ## Replying to messages To reply to a coord message (e.g., answering a question from another user): ```bash bash "$CLAUDETOOLS_ROOT/.claude/scripts/py.sh" "$CLAUDETOOLS_ROOT/.claude/skills/coord/scripts/coord.py" \ msg send "Re: " "" ``` - `` can be a bare machine name (e.g., `Howard-Home`), full session ID, or `ALL` for broadcast - Use `--body-file ` for multi-line replies - The reply is a new message; there's no threading (yet) ## Notes - API base comes from `identity.json` `coord_api` (default `http://172.16.3.30:8001`); the script appends `/api/coord`. - Softfail: if the API is unreachable the command errors (exit 1). Per the coord protocol, queue failed writes to `.claude/coord-queue.jsonl` and drain on `/sync` if doing this manually. - Full protocol + endpoint detail: `.claude/COORDINATION_PROTOCOL.md` and CLAUDE.md "Live State Tracking".