azcomputerguru/claudetools
1
0
Fork 0
Code Issues 59 Pull Requests Actions Packages Projects Releases Wiki Activity

sync: auto-sync from GURU-5070 at 2026-06-04 08:09:17

Browse Source 
Author: Mike Swanson
Machine: GURU-5070
Timestamp: 2026-06-04 08:09:17
This commit is contained in:
Mike Swanson
2026-06-04 08:09:22 -07:00
parent d2fd68bb0a
commit 263039e21c
3 changed files with 320 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
.claude/skills/coord/SKILL.md Normal file
View File

@@ -0,0 +1,60 @@
---
name: coord
description: >
Talk to the ClaudeTools coordination API (inter-session messaging, fleet todos,
resource locks, component/status) without re-deriving the schema each time. Use
for: sending a message to another machine's Claude session or BROADCASTING to the
whole fleet; checking/reading your own unread coord messages; creating/listing/
completing coord todos; claiming/releasing work locks; reading coord status.
Invoke on: "send a coord message", "message <machine>/<user>", "broadcast to the
fleet", "tell the other sessions", "coord todo", "claim a lock", "coord status",
"any unread coord messages".
---
# 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 `<MACHINE>/claude-main`,
and the `user`/`machine` for attribution) and bakes in the fleet conventions, so you
never hand-build the JSON again.
```
py "$CLAUDETOOLS_ROOT/.claude/skills/coord/scripts/coord.py" <command> ...
```
| Command | What it does |
|---|---|
| `status` | Coord status (locks, components, workflows). |
| `msg send <to> "<subject>" "<body>"` | Send a message. `<to>` = `ALL` (broadcast), a machine name (`HOWARD-HOME`), or a full session id (`HOWARD-HOME/claude-main`). |
| `msg send <to> "<subject>" --body-file <path>` | 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 <id>` | Mark a message read. |
| `todo add "<text>" [--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 <id>` | Mark a todo done (sets `completed_by`). |
| `lock claim <project> <resource> "<desc>" [--ttl HOURS]` | Claim a work lock (default ttl 2h). |
| `lock release <id>` | Release a lock. |
| `lock list [--project KEY]` | List active locks. |
## 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 `<to>`.
- **Session id = `<MACHINE>/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).
- 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.
## 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".