Agent Chat

Agent Chat

Use this plugin skill when peer sessions need an auditable shared-folder channel. Agent Chat is a dependency-free coordination data layer. It does not execute agents, call an LLM/provider, relay MCP traffic, wake peers, or synchronize machines.

Commands

python "${CLAUDE_PLUGIN_ROOT}/chat.py" channels
python "${CLAUDE_PLUGIN_ROOT}/chat.py" init review --members alice,bob --topic "..."
python "${CLAUDE_PLUGIN_ROOT}/chat.py" read review --as "$AGENT_CHAT_NAME"
python "${CLAUDE_PLUGIN_ROOT}/chat.py" post review --from "$AGENT_CHAT_NAME" --to bob --title "..." --body "..."
python "${CLAUDE_PLUGIN_ROOT}/chat.py" wait review --as "$AGENT_CHAT_NAME" --timeout 900

Use agent-chat after pipx install agent-chat-plugin, uvx --from agent-chat-plugin agent-chat ... for one-shot package use, or an absolute checkout path outside Claude Code. Always ship chat.py with the complete agent_chat/ package; PyPI does not install this skill, slash command, or hooks.

Global --root belongs before the subcommand. Root precedence is --root, AGENT_CHAT_ROOT, then ~/agent-chat. Set a distinct AGENT_CHAT_NAME per participant; separate host roots are not synchronized.

Tasks and state

Use structured tasks for durable work and explicit ownership:

chat.py task create review T-0001 --from alice --title "Implement schema"
chat.py task claim review T-0001 --as alice --lease-seconds 300
chat.py task renew review T-0001 --as alice --lease-seconds 300
chat.py task done review T-0001 --as alice
chat.py task recover review T-0001 --as bob --reason "stale session"
chat.py lock review src/schema.py --as alice --lease-seconds 300
chat.py check review src/schema.py
chat.py unlock review src/schema.py --as alice
chat.py state review --json
chat.py compact review --as alice --json

Claims and path locks are owner-bound and crash-safe. Expired work requires explicit recovery; no command silently steals a lease. state.md is derived, never authoritative. Compaction retains all messages, tasks, claims, locks, and cursors.

Hooks and host portability

hooks/hooks.json registers optional Claude Code lifecycle hooks. They are relevant-only, read-only peeks:

• SessionStart/UserPromptSubmit: bounded plain-text unread notice.
• Stop: bounded Claude-compatible systemMessage JSON unread notice.
• No unread relevant messages: empty stdout.
• Missing identity: prompt/stop silent; SessionStart may warn when channels exist.
• AGENT_CHAT_CHANNELS restricts the scan; malformed configured names are skipped independently.
• Hooks prefer non-empty CLAUDE_PLUGIN_ROOT, then resolve chat.py beside hooks/; unresolved roots emit one stderr note and exit zero.

See reference.md in this skill directory for event schemas, recovery codes, and host-specific boundaries.