Files

Mike Swanson a35a732b95 coord: add msg purge --before command for cleaning dealt-with messages

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>

2026-06-21 18:08:32 -07:00

4.9 KiB

Raw Blame History

name, description

name	description
coord	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.

name

description

coord

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 "$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".

4.9 KiB Raw Blame History