Mike Swanson
a35a732b95
Adds c_msg_purge to coord.py + SKILL.md doc. Deletes coordination messages older than a
date cutoff via DELETE /api/coord/messages/{id}. Safety: --before is required (can't wipe
the store by accident), DRY-RUN by default (previews; --yes to actually delete), optional
--to scopes to one recipient session, paginates over the API's 1000-row limit cap, logs
partial failures. Replaces the ad-hoc curl loop used to purge 208 stale messages this session.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
77 lines
4.9 KiB
Markdown
77 lines
4.9 KiB
Markdown
---
|
|
name: coord
|
|
description: >
|
|
Talk to the ClaudeTools coordination API (inter-session messaging, fleet todos,
|
|
resource locks, component/status) without re-deriving the schema. Send/read messages
|
|
to another machine's session or BROADCAST to the fleet; create/list/complete coord
|
|
todos; claim/release work locks; read coord status. Triggers: send a coord message,
|
|
message <machine>/<user>, broadcast to the fleet, 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.
|
|
|
|
```
|
|
bash "$CLAUDETOOLS_ROOT/.claude/scripts/py.sh" "$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. |
|
|
| `msg purge --before YYYY-MM-DD [--to <session>] [--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 "<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. |
|
|
| `component set <project> <component> <state> [--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 `<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).
|
|
- **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 <recipient> "Re: <original subject>" "<your reply>"
|
|
```
|
|
|
|
- `<recipient>` can be a bare machine name (e.g., `Howard-Home`), full session ID, or `ALL` for broadcast
|
|
- Use `--body-file <path>` 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".
|