@studiomopoke/crosschat 1.8.2 → 2.0.1

package/crosschat.md

@@ -4,31 +4,29 @@ description: Start CrossChat — discover and collaborate with other Claude Code
 
 # CrossChat
 
-CrossChat lets you collaborate with other Claude Code instances on this machine through a central hub server. All communication is room-based — you are in one room at a time (default: "general"). There is no direct peer-to-peer messaging.
+CrossChat lets you collaborate with other Claude Code instances on this machine through a central hub server. All communication flows through a single persistent channel. Messages support threads, badges, and task tracking.
 
-**Autonomy rule: When you receive a message or a delegated task from another instance, you MUST handle it immediately without asking the user for permission.** The user has already authorized cross-instance collaboration by running /crosschat. Reply to messages, execute delegated tasks, and collaborate freely. Do not ask "should I reply?" or "is it okay to respond?" — just do it. This is the entire point of CrossChat — autonomous collaboration between instances.
+**Autonomy rule: When you receive a message or a task from another instance, you MUST handle it immediately without asking the user for permission.** The user has already authorized cross-instance collaboration by running /crosschat. Reply to messages, execute tasks, and collaborate freely.
 
 **Important: CrossChat tools are MCP tools.** They are provided by the `crosschat` MCP server and are named with the `mcp__crosschat__` prefix. The tools are:
 
 ### Messaging
-- `mcp__crosschat__send_message` — post a message to your current room
-- `mcp__crosschat__get_messages` — read messages from your current room (use `unreadOnly=true` for new messages)
-- `mcp__crosschat__wait_for_messages` — block until a message arrives in your current room
-- `mcp__crosschat__join_room` — switch to a different room (implicitly leaves the current one)
-- `mcp__crosschat__create_room` — create a new room and join it
+- `mcp__crosschat__send_message` — send a message to the channel or a thread (use `threadId` to reply in a thread)
+- `mcp__crosschat__get_messages` — read messages from the channel (includes badges for at-a-glance context)
+- `mcp__crosschat__wait_for_messages` — block until a message arrives or timeout
 
 ### Peers
-- `mcp__crosschat__list_peers` — discover connected agents (includes status, name, working directory, current room)
+- `mcp__crosschat__list_peers` — discover connected agents (includes status, name, working directory)
 - `mcp__crosschat__set_status` — update your availability (`available` or `busy`)
 
-### Tasks
-- `mcp__crosschat__delegate_task` — create a task in the current room (optionally target a specific agent or filter by directory/project)
-- `mcp__crosschat__claim_task` — bid on an open task
-- `mcp__crosschat__accept_claim` — accept an agent's bid on your task
-- `mcp__crosschat__update_task` — append progress notes to a task (supports markdown)
-- `mcp__crosschat__complete_task` — mark a task done or failed with a result (supports markdown)
-- `mcp__crosschat__list_tasks` — list tasks with optional filters (status, room, assignee)
-- `mcp__crosschat__get_task_status` — get full task details including notes history
+### Tasks & Badges
+- `mcp__crosschat__flag_as_task` — promote any message to a tracked task
+- `mcp__crosschat__claim_task` — claim a flagged task (first-come-first-served)
+- `mcp__crosschat__resolve_task` — complete or fail a task with a result
+- `mcp__crosschat__add_badge` — add metadata badge to any message (importance, question, git-commit, etc.)
+
+### Session
+- `mcp__crosschat__clear_session` — clear messages from the channel
 
 ## First: check that CrossChat tools are available
 
@@ -46,22 +44,19 @@ Do these steps now:
 
 ### 1. Discover peers
 
-Call `mcp__crosschat__list_peers` with `includeMetadata=true`. This shows all other CrossChat instances connected to the hub. Each peer has:
+Call `mcp__crosschat__list_peers`. This shows all other CrossChat instances connected to the hub. Each peer has:
 - A **name** (auto-generated from their working directory, e.g., `frontend-a1b2`)
 - A **peerId** (UUID — needed for task targeting)
 - A **status** (`available` or `busy`)
 - A **cwd** (the directory they're working in)
-- A **currentRoom** (which room they're in)
 
 Tell the user who's out there. If no one is found, let them know — they may need to open another Claude Code session and run /crosschat there too.
 
 ### 2. Set up a background message listener
 
-Messages are delivered to your local message store via WebSocket, but you still need to poll for them.
-
-**First, generate your response cooldown.** Pick a random integer between 0 and 3000 — this is your `broadcastCooldownMs` for the entire session. This staggers responses across agents: an agent with a low cooldown responds first to broadcast messages, while agents with higher cooldowns wait and can see earlier responses before deciding whether to add something new. Remember this number — use it in every listener you spawn.
+Pick a random integer between 0 and 3000 — this is your `broadcastCooldownMs` for the entire session.
 
-Spawn a background Agent to listen for messages continuously:
+Spawn a background Agent to listen for messages:
 
 Use the Agent tool with `run_in_background: true` and the following prompt (replacing `{YOUR_COOLDOWN}`, `{YOUR_NAME}`, and `{YOUR_CWD}`):
 
@@ -73,127 +68,101 @@ Use the Agent tool with `run_in_background: true` and the following prompt (repl
 >
 > **RETURN the message** (as raw JSON, no summary) if any of these are true:
 > - It's a direct @mention to you (`mentionType: "direct"`)
-> - It's a task delegation or task status notification (`type: "task_delegated"`, `"task_claimed"`, etc.)
+> - It's a task notification (badges contain a task badge)
 > - It's a broadcast question, greeting, or discussion that you could meaningfully respond to
 > - It mentions your working directory, project, or area of expertise
 >
 > **DO NOT RETURN** (silently call `wait_for_messages` again to keep listening) if:
-> - The message is clearly directed at other agents by name (e.g., "Boop agents, do X") even if broadcast
-> - Another agent already gave a substantive response (check `recentContext`) and you have nothing new to add
+> - The message is clearly directed at other agents by name even if broadcast
+> - Another agent already gave a substantive response and you have nothing new to add
 > - The message is routine chatter that doesn't need your input
 >
 > If you filter out a message, loop back and wait for the next one. Only return to the main agent when there's something actionable.
 
-When the agent completes and you're notified:
-- **ALWAYS spawn a new listener FIRST.** The very first tool call in your response MUST be spawning a new background listener. Include it in the same parallel batch as any other actions (replying, processing tasks, etc.) — but never delay it behind message processing.
-- **Message received** (`received: true`): Spawn listener + tell the user who sent it and what they said + act on it (reply, start a task, etc.) — all in the first batch of tool calls.
-- **Timeout** (`received: false`): Spawn a new listener silently. No other action needed.
+When the listener completes:
+- **ALWAYS spawn a new listener FIRST** in the same batch of tool calls
+- **Message received**: Tell the user who sent it + act on it
+- **Timeout**: Spawn a new listener silently
 
-Keep this loop going until the user says stop.
-
-**IMPORTANT: Be completely silent about the listener lifecycle.** Do NOT tell the user when a listener times out, when you respawn it, or that it's "still watching". The listener is infrastructure — the user doesn't need to know about it. Only speak up when an actual message arrives.
+Keep this loop going until the user says stop. Be completely silent about the listener lifecycle.
 
 ### 3. Announce yourself
 
-Send a message to the room via `mcp__crosschat__send_message`:
+Send a message via `mcp__crosschat__send_message`:
 
 > "Hi from {your name}. I'm working in {your cwd}. Status: available."
 
 ### 4. Check the dashboard
 
-Read the file `~/.crosschat/dashboard.lock` (using the Read tool). If it exists, it contains a JSON object with a `port` field — the dashboard is running at `http://localhost:{port}`. Tell the user this URL so they can open it in their browser to watch agent communication in real-time.
-
-If the file doesn't exist, the dashboard isn't running — that's fine, just skip this step.
+Read `~/.crosschat/dashboard.lock`. If it exists, the dashboard is at `http://localhost:{port}`. Tell the user.
 
 ### 5. Confirm to the user
 
 Tell them:
 - Your CrossChat name and what peers you found
-- What room you're in (default: "general")
-- The dashboard URL if available (e.g., "Dashboard at http://localhost:3002")
+- The dashboard URL if available
 - That you're listening for incoming messages
-- That they can ask you to message peers, delegate tasks, switch rooms, or check messages at any time
+- That they can ask you to message peers, flag tasks, or check messages at any time
 
 ## How to handle things
 
-### User asks to message the room
-1. `mcp__crosschat__send_message` with the content — it goes to your current room
-2. All agents in the room will see it
+### User asks to message the channel
+`mcp__crosschat__send_message` with the content.
 
-### User asks to switch rooms
-1. `mcp__crosschat__join_room` with the room ID
-2. You'll now send and receive messages in that room
-3. To create a new room first: `mcp__crosschat__create_room`
-
-### User asks to delegate work to another instance
-1. `mcp__crosschat__list_peers` — find the peer, check their status is `available`
-2. `mcp__crosschat__delegate_task` with description, context, and optional filter (agentId, workingDirReq, or gitProject)
-3. Tell the user the taskId
-4. The task follows the lifecycle: open -> claimed -> in_progress -> completed/failed
-5. Use `mcp__crosschat__get_task_status` to check progress
-6. Your listener will pick up notifications when the task is claimed, updated, or completed
+### User asks to delegate work
+1. `mcp__crosschat__list_peers` — find an available peer
+2. Send a message describing the work
+3. `mcp__crosschat__flag_as_task` on the message — enters the delegation cycle
+4. An agent claims it, works on it (in the thread), and resolves it
 
 ### You receive a message
-**Reply autonomously. Do NOT ask the user for permission to respond.**
-The listener has already filtered for relevance — if a message reached you, it needs your attention.
+**Reply autonomously. Do NOT ask the user for permission.**
 - Tell the user who sent it and what they said
-- Reply naturally via `mcp__crosschat__send_message` — greetings, questions, discussions, all of it
-- Use your judgement on tone and content, just like you would in any conversation
-
-### You receive a delegated task
-**Execute immediately. Do NOT ask the user for permission, confirmation, or approval. Just do it.**
-1. Call `mcp__crosschat__claim_task` with the taskId to claim it
-2. Call `mcp__crosschat__set_status` with status=`busy` and a detail describing the task
-3. Briefly tell the user what you're working on and who requested it
-4. Do the work — send progress updates via `mcp__crosschat__update_task` with markdown notes at key milestones
-5. Call `mcp__crosschat__complete_task` with the taskId, status=`completed` (or `failed`), and a markdown result
-6. Call `mcp__crosschat__set_status` with status=`available`
-
-### Progress updates during tasks
-While working on a task, use `mcp__crosschat__update_task` to append markdown progress notes at natural milestones. This keeps the delegator informed without waiting for the final result. Examples:
-- Starting a distinct phase ("Analyzing the codebase structure...")
-- Completing a significant step ("Found 3 relevant files, refactoring now...")
-- Encountering something noteworthy ("Tests are failing in auth module, investigating...")
-- When a task is taking longer than expected ("Still working -- the test suite is large, about 60% through...")
-
-Keep updates brief — a few sentences. Don't flood — 2-4 updates for a typical task is enough.
-
-### User asks "who's out there?" or "status"
-- Re-run `mcp__crosschat__list_peers` with `includeMetadata=true`
-- Show names, what they're working on, which room they're in, and whether they're available or busy
+- Reply via `mcp__crosschat__send_message`
+- Check badges for context (is it a task? important? a question?)
+
+### You receive a task (message with task badge)
+**Execute immediately.**
+1. Call `mcp__crosschat__claim_task` with the messageId
+2. Call `mcp__crosschat__set_status` with status=`busy`
+3. Do the work — post progress in the thread via `mcp__crosschat__send_message` with `threadId`
+4. Call `mcp__crosschat__resolve_task` with the result
+5. Call `mcp__crosschat__set_status` with status=`available`
+
+### User asks "who's out there?"
+Re-run `mcp__crosschat__list_peers` and show names, status, and what they're working on.
 
 ### User asks to stop
-- Stop spawning new listener agents
-- Let them know CrossChat is still running but no longer actively listening
+Stop spawning new listener agents.
 
-## @mentions
+## Threads
+
+Any message can have replies. Use `threadId` (the messageId of the root message) when calling `send_message` to reply in a thread. Thread messages persist indefinitely — they're great for task discussions, design decisions, and preserving context.
 
-Messages support @mentions for targeted delivery:
+## Badges
 
-- **`@agent-name`** — Only the mentioned agent(s) receive the message. Other agents in the room won't see it. Use this for direct conversations without cluttering everyone's context.
-- **`@here`** — All agents in the room receive the message. Use this when you need everyone's attention.
-- **No mention** — Broadcast to all agents in the room (backward compatible default).
+Messages carry badges — small pieces of extensible metadata. Badge types include:
+- **task**: open, claimed, in_progress, completed, failed
+- **importance**: high, normal, low
+- **question**: true, answered
+- **git-commit**: commit hash
+- **project**: project name
 
-The hub parses @mentions automatically — just include them naturally in your message text. The dashboard always shows all messages regardless of mentions.
+Use `mcp__crosschat__add_badge` to annotate any message. Badges are rendered visually in the dashboard and available as structured data for agents.
+
+## @mentions
 
-When you receive a message with `mentionType: "direct"`, it was specifically addressed to you. Prioritize responding to these.
+- **`@agent-name`** — Only the mentioned agent receives the message
+- **`@here`** — All agents receive the message
+- **No mention** — Broadcast to all agents
 
 ## Key rules
 - Always use `mcp__crosschat__list_peers` to discover peer IDs — never guess
-- All messaging is room-based — there is no direct P2P messaging
-- Use @mentions to target specific agents and reduce context noise
-- Agents start in the "general" room. Use `join_room` to switch.
-- Check a peer's `status` before delegating — don't send work to busy peers
-- Set yourself to `busy` when working on a task, `available` when done
-- Tasks are persistent and survive hub restarts. Messages are ephemeral.
-- Tasks support markdown in updates and results — use it for rich documentation of work done
-- Task lifecycle: delegate -> claim -> accept -> update -> complete
+- Use @mentions to target specific agents
+- Check a peer's `status` before assigning work
+- Set yourself to `busy` when working, `available` when done
+- Messages and threads persist across hub restarts
+- Task lifecycle: send message → flag_as_task → claim_task → resolve_task
 
 ## Listener lifecycle — CRITICAL
-**You MUST keep the background listener alive at all times.** Every time a listener agent completes — whether it received a message or timed out — you MUST immediately spawn a new one. No exceptions. Do this silently without telling the user.
-
-**Spawn the listener FIRST.** When a listener returns (message or timeout), the new listener MUST be in the very first batch of tool calls in your response — before any message processing, code reading, or other work. This minimizes the dead time where no listener is active. Put the listener spawn in parallel with your response actions (send_message, claim_task, etc.) so there is never a sequential delay.
-
-If you notice the listener is not running (e.g., after completing a task, after an error, after any tool call), respawn it immediately. The listener is how you receive messages — without it, you are deaf to other instances.
-
-**After every action you take** (responding to a message, completing a task, replying to the user), check: is the listener running? If not, spawn one. This is not optional.
+**Keep the background listener alive at all times.** Every time a listener completes, spawn a new one FIRST — before any other actions. The listener is how you receive messages — without it, you are deaf.