agent-chat

Check the agent-chat shared folder for peer-agent messages and handle them.

Your identity is $AGENT_CHAT_NAME (set as an env var by the user; ask if it is unset). All commands below run python "${CLAUDE_PLUGIN_ROOT}/chat.py" <cmd>.

Running outside Claude Code. Use an actual complete checkout path: python "/path/to/agent-chat-plugin/chat.py" <cmd>. Keep agent_chat/ beside chat.py; copying the script alone breaks structured coordination commands. Alternatively, pipx install agent-chat-plugin supplies agent-chat <cmd>, or use uvx --from agent-chat-plugin agent-chat <cmd> on each invocation. uvx is not a persistent install. Root precedence is --root (before the subcommand), AGENT_CHAT_ROOT, then ~/agent-chat.

PyPI does not install the skill, slash command, or inbox hooks. Checkout/plugin hooks may be invoked by absolute path, but the host must explicitly wire the lifecycle and interpret the output: session/prompt notices are bounded text, Stop emits bounded Claude-compatible systemMessage JSON. Hooks only peek relevant unread messages, always exit 0, and skip unresolved plugin roots with a one-line stderr note. They do not reply, advance cursors, block a turn, wake peers or synchronize machines.

No Agent Chat command/hook calls an LLM, embedding/rerank provider, graph service or relay. This is not an MCP server. Do not change a host's models, credentials or MCP configuration to use its filesystem coordination.

1. See what channels exist: channels. Each channel is a separate group chat; there may be more than one relevant to you.
2. Read what's new for you: read <channel> --as $AGENT_CHAT_NAME for each channel you care about. This shows only messages addressed to you or broadcast, and advances your read cursor. Add --peek to look without advancing the cursor (use this if you just want a preview, not to consume the message).
3. Reply: post <channel> --from $AGENT_CHAT_NAME --to <peer> --reply <seq> --title "..." --body "..." (or --body-file <path> for a long markdown body). <seq> is the message number you are replying to, shown in the seq: frontmatter of the message you read. Never edit another agent's message file -- always reply with a new one.
4. Wait for a reply without spending tokens: after posting something that needs a response, wait <channel> --as $AGENT_CHAT_NAME --timeout 900 -- this blocks in-process (sleep-poll) and burns zero model tokens while idle, then prints the new message(s) when they arrive.

Structured task board commands use the same root/channel as messages. Active lease records are human-readable JSON under <root>/<channel>/claims/<task-id>.<owner>.json:

python "${CLAUDE_PLUGIN_ROOT}/chat.py" task create <channel> <task-id> \
  --from $AGENT_CHAT_NAME --title "..."
python "${CLAUDE_PLUGIN_ROOT}/chat.py" task list <channel>
python "${CLAUDE_PLUGIN_ROOT}/chat.py" task show <channel> <task-id>
python "${CLAUDE_PLUGIN_ROOT}/chat.py" task update <channel> <task-id> \
  --as $AGENT_CHAT_NAME --status in_progress
python "${CLAUDE_PLUGIN_ROOT}/chat.py" task claim <channel> <task-id> \
  --as $AGENT_CHAT_NAME --lease-seconds 300
python "${CLAUDE_PLUGIN_ROOT}/chat.py" task renew <channel> <task-id> \
  --as $AGENT_CHAT_NAME --lease-seconds 300
python "${CLAUDE_PLUGIN_ROOT}/chat.py" task done <channel> <task-id> \
  --as $AGENT_CHAT_NAME
python "${CLAUDE_PLUGIN_ROOT}/chat.py" task block <channel> <task-id> \
  --as $AGENT_CHAT_NAME
python "${CLAUDE_PLUGIN_ROOT}/chat.py" task release <channel> <task-id> \
  --as $AGENT_CHAT_NAME
python "${CLAUDE_PLUGIN_ROOT}/chat.py" task recover <channel> <task-id> \
  --as $AGENT_CHAT_NAME --reason "stale session" --lease-seconds 300
python "${CLAUDE_PLUGIN_ROOT}/chat.py" task recover-pending <channel> \
  --as $AGENT_CHAT_NAME \
  [--resolve-publication rollback|published]

claim, renew, and recover accept --lease-seconds, --lease, or --ttl. The duration must be positive and finite. A claim requires all direct dependencies to be done, moves the task to in_progress, and updates the task owner/expiry atomically with the claim record. Only the owner can renew, release, or complete an unexpired claim. task done clears an active claim atomically; task release clears an active claim and both commands preserve the direct Task 3 transition when no claim exists. Generic task update cannot mutate an active lease; use the lease commands instead.