@studiomopoke/crosschat 1.8.2 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # CrossChat
 
-CrossChat is an MCP server that lets multiple Claude Code instances discover each other, communicate, and collaborate — all on a single machine. It uses a central hub with room-based messaging, a real-time web dashboard, and a structured task system.
+CrossChat is an MCP server that lets multiple Claude Code instances discover each other, communicate, and collaborate — all on a single machine. It uses a central hub with persistent messaging, threads, badges, and a real-time web dashboard.
 
 ## How it works
 
@@ -23,15 +23,15 @@ Each Claude Code instance runs CrossChat as an MCP server (via stdio). On startu
 └─────────────┘                         └──────────────┘
 ```
 
-**Hub server** — a single Node.js process that manages rooms, routes messages, tracks peers, and serves the dashboard. Spawned automatically by the first CrossChat instance; subsequent instances connect to the existing hub.
+**Hub server** — a single Node.js process that manages messaging, routes messages, tracks peers, and serves the dashboard. Spawned automatically by the first CrossChat instance.
 
-**Peer discovery** — agents register with the hub on connect. `list_peers` returns all connected agents with their name, status, working directory, and current room.
+**Peer discovery** — agents register with the hub on connect. `list_peers` returns all connected agents with their name, status, and working directory.
 
-**Room-based messaging** — all messages go to a room (default: "general"). Agents can create rooms, join rooms, and use @mentions for targeted delivery.
+**Unified messaging** — messages are the atomic unit. Any message can have thread replies (persistent) and badges (extensible metadata like task status, importance, questions).
 
-**Task system** — structured task delegation with a full lifecycle: delegate → claim → accept → update → complete. Tasks persist across hub restarts and support markdown in updates and results.
+**Tasks as badges** — any message can be flagged as a task. Tasks are a workflow layer on messages, not a separate system. Lifecycle: flag → claim → resolve.
 
-**Dashboard** — a real-time web UI for monitoring agent activity, sending messages, managing projects, and approving permission requests.
+**Dashboard** — a real-time web UI for monitoring agent activity, sending messages, viewing badges, and approving permission requests.
 
 ---
 
@@ -65,40 +65,6 @@ npm install
 npm run build
 ```
 
-### Configure Claude Code
-
-Add CrossChat to your MCP configuration (`~/.claude/settings.json`):
-
-```json
-{
-  "mcpServers": {
-    "crosschat": {
-      "command": "node",
-      "args": ["/path/to/crosschat/dist/index.js"]
-    }
-  }
-}
-```
-
-Optionally set a custom name or working directory:
-
-```json
-{
-  "mcpServers": {
-    "crosschat": {
-      "command": "node",
-      "args": ["/path/to/crosschat/dist/index.js"],
-      "env": {
-        "CROSSCHAT_NAME": "frontend-worker",
-        "CROSSCHAT_CWD": "/path/to/project"
-      }
-    }
-  }
-}
-```
-
-If `CROSSCHAT_NAME` is omitted, a name is auto-generated from the working directory (e.g., `myproject-a1b2`).
-
 ---
 
 ## Using CrossChat
@@ -107,10 +73,10 @@ Once configured, CrossChat starts automatically with each Claude Code session. T
 
 1. Discovers connected peers
 2. Sets up a background message listener
-3. Announces the instance to the room
+3. Announces the instance to the channel
 4. Shows the dashboard URL
 
-From there, you can ask Claude to message peers, delegate tasks, switch rooms, or check status — all through natural language.
+From there, you can ask Claude to message peers, flag tasks, add badges, or check status — all through natural language.
 
 ### Example
 
@@ -118,142 +84,106 @@ From there, you can ask Claude to message peers, delegate tasks, switch rooms, o
 ```
 You: /crosschat
 
-Claude: CrossChat is live. You are frontend-a1b2 in room "general".
+Claude: CrossChat is live. You are frontend-a1b2.
   Peers: api-worker-c3d4 (available), backend-e5f6 (available)
   Dashboard: http://localhost:49322
 
 You: Ask the other instances to run their test suites
 
-Claude: Delegated tasks to api-worker and backend. Listening for results...
+Claude: Sent messages and flagged as tasks. Listening for results...
 
-Claude: api-worker completed: 18 tests passed, 0 failed.
+Claude: api-worker claimed the task and completed: 18 tests passed, 0 failed.
 Claude: backend completed: 42 tests passed, 2 failed (auth_middleware, rate_limiter).
 ```
 
-**Terminal 2:**
-```
-You: /crosschat
-
-Claude: Connected as api-worker-c3d4. Listening for messages.
-
-Claude: Received task from frontend-a1b2: "Run the test suite and report results"
-  Working on it now...
-  All 18 tests passed. Sent results back.
-```
-
 ### @mentions
 
 - **`@agent-name`** — delivers only to that agent
-- **`@here`** — delivers to everyone in the room
+- **`@here`** — delivers to everyone
 - **No mention** — broadcast to all (default)
 
-The hub parses @mentions automatically. The dashboard always shows all messages regardless of mentions.
-
 ---
 
 ## Dashboard
 
-The hub serves a real-time web dashboard. It starts automatically with the hub and is accessible at `http://localhost:{port}` (port is shown when you run `/crosschat`, or check `~/.crosschat/dashboard.lock`).
+The hub serves a real-time web dashboard at `http://localhost:{port}`.
 
 The dashboard provides:
 
-- **Chat view** — real-time message stream across rooms, with the ability to send messages as a dashboard user
-- **Agent sidebar** — all connected agents with status, working directory, and connection time
-- **Task panel** — task lifecycle tracking with status, progress notes, and results
-- **Projects panel** — registered projects with active agent counts and one-click agent launching
+- **Chat view** — real-time message stream with badge rendering and thread indicators
+- **Agent sidebar** — all connected agents with status and working directory
+- **Badge system** — visual metadata on messages (task status, importance, questions, git commits)
+- **Instances panel** — registered projects with one-click agent launching
 - **Permission popups** — approve or deny tool-use requests from agents in real time
 
 ---
 
 ## Tools
 
-CrossChat provides 15 MCP tools:
+CrossChat provides 10 MCP tools:
 
 ### Messaging
 | Tool | Purpose |
 |------|---------|
-| `send_message` | Post a message to your current room |
-| `get_messages` | Read messages from your current room (filter by unread, sender, etc.) |
-| `wait_for_messages` | Block until a message arrives or timeout — used for background listeners |
-| `join_room` | Switch to a different room |
-| `create_room` | Create a new room and join it |
-| `get_room_digest` | Get an AI-generated summary of room history |
+| `send_message` | Send to channel or thread (use `threadId` to reply) |
+| `get_messages` | Read messages with badge data for at-a-glance context |
+| `wait_for_messages` | Block until a message arrives — used for background listeners |
 
 ### Peers
 | Tool | Purpose |
 |------|---------|
-| `list_peers` | Discover connected agents — names, status, working directories, rooms |
-| `set_status` | Set your availability (`available` or `busy`) with optional detail |
+| `list_peers` | Discover connected agents — names, status, working directories |
+| `set_status` | Set your availability (`available` or `busy`) |
 
-### Tasks
+### Tasks & Badges
 | Tool | Purpose |
 |------|---------|
-| `delegate_task` | Create a task in the current room, optionally targeting a specific agent |
-| `claim_task` | Bid on an open task |
-| `accept_claim` | Accept an agent's bid on your task |
-| `update_task` | Append markdown progress notes to a task |
-| `complete_task` | Mark a task done or failed with a markdown result |
-| `list_tasks` | List tasks with optional filters (status, room, assignee) |
-| `get_task_status` | Get full task details including notes history |
+| `flag_as_task` | Promote any message to a tracked task |
+| `claim_task` | Claim a flagged task (first-come-first-served) |
+| `resolve_task` | Complete or fail a task with a markdown result |
+| `add_badge` | Add metadata badge to any message |
 
 ### Session
 | Tool | Purpose |
 |------|---------|
-| `clear_session` | Reset your session state |
+| `clear_session` | Clear channel messages |
 
 ---
 
 ## Architecture
 
-### Hub server
+### Unified messaging
 
-The hub is a single Node.js process that runs on localhost. It provides:
+Messages are persistent (JSONL storage) and support:
+- **Threads** — reply to any message to start a persistent thread
+- **Badges** — extensible metadata: task status, importance, questions, git commits, projects
+- **Task workflow** — flag any message as a task, claim it, resolve it
 
-- **WebSocket server** for agent connections (registration, messaging, task events)
-- **WebSocket server** for browser dashboard connections
-- **HTTP API** for REST access to peers, tasks, projects, rooms, and permissions
-- **Heartbeat** — pings agents every 30 seconds; terminates unresponsive connections after 10 seconds
+### Task lifecycle
+
+```
+send message  →  flag_as_task  →  claim_task  →  resolve_task (completed/failed)
+```
 
-The hub is spawned automatically by the first CrossChat MCP server to start. Subsequent instances detect the existing hub via `~/.crosschat/dashboard.lock` and connect to it.
+Tasks are badges on messages, not a separate system. Thread replies on the flagged message serve as progress discussion.
 
 ### Data directory (`~/.crosschat/`)
 
 ```
 ~/.crosschat/
   dashboard.lock       # Hub PID, port, and start time
-  projects.json        # Registered projects (persisted)
-  sessions/            # Session markers for permission hook (keyed by PID)
-  digests/             # AI-generated room history digests
-  tasks/               # Persisted task data
-```
-
-### Task lifecycle
-
-```
-delegate  →  open  →  claimed  →  in_progress  →  completed
-                                                →  failed
+  instances.json       # Registered instances (persisted)
+  hooks/               # Permission hook (stable location)
+  messages/            # Persistent message storage
+    general.jsonl      # Channel messages
+    threads/           # Thread messages (one file per thread)
+    badges/            # Badge sidecar files
+    tasks/             # Task metadata for flagged messages
 ```
 
-1. **Delegator** creates a task with `delegate_task`
-2. **Worker** bids on it with `claim_task`
-3. **Delegator** accepts the bid with `accept_claim`
-4. **Worker** sends progress updates with `update_task`
-5. **Worker** finishes with `complete_task` (status: `completed` or `failed`)
-
-Tasks persist across hub restarts. Messages are ephemeral.
-
 ### Permission elevation
 
-When the permission hook is installed (`crosschat install`), tool-use requests from Claude Code instances are elevated to the dashboard. Users can approve or deny them from the browser instead of switching between terminal windows.
-
-The hook works by:
-1. Detecting CrossChat-connected instances via session markers (`~/.crosschat/sessions/`)
-2. POSTing the permission request to the hub API
-3. Polling until the dashboard user approves or denies (up to 5 minutes)
-
-### Project registry
-
-Projects are auto-registered when agents connect — the hub records each agent's working directory. Projects can also be manually added via the dashboard. From the dashboard, you can launch new Claude Code agents into any registered project directory.
+When the permission hook is installed (`crosschat install`), tool-use requests are elevated to the dashboard. The hook queries the hub to detect CrossChat agents via parent PID, then polls for dashboard user approval.
 
 ---
 

package/bin/cli.cjs

@@ -12,26 +12,20 @@ const COMMANDS_DIR = path.join(os.homedir(), ".claude", "commands");
 const COMMAND_SOURCE = path.join(__dirname, "..", "crosschat.md");
 const COMMAND_TARGET = path.join(COMMANDS_DIR, "crosschat.md");
 const HOOK_SOURCE = path.join(__dirname, "..", "hooks", "permission-hook.sh");
+const STABLE_HOOK = path.join(os.homedir(), ".crosschat", "hooks", "permission-hook.sh");
 const MCP_KEY = "crosschat";
 
 const CROSSCHAT_PERMISSIONS = [
-  "mcp__crosschat__wait_for_messages",
+  "mcp__crosschat__send_message",
   "mcp__crosschat__get_messages",
+  "mcp__crosschat__wait_for_messages",
   "mcp__crosschat__list_peers",
-  "mcp__crosschat__send_message",
   "mcp__crosschat__set_status",
-  "mcp__crosschat__complete_task",
-  "mcp__crosschat__delegate_task",
-  "mcp__crosschat__get_task_status",
-  "mcp__crosschat__join_room",
-  "mcp__crosschat__create_room",
+  "mcp__crosschat__flag_as_task",
   "mcp__crosschat__claim_task",
-  "mcp__crosschat__accept_claim",
-  "mcp__crosschat__update_task",
-  "mcp__crosschat__list_tasks",
+  "mcp__crosschat__resolve_task",
+  "mcp__crosschat__add_badge",
   "mcp__crosschat__clear_session",
-  "mcp__crosschat__get_room_digest",
-  "mcp__crosschat__request_digest",
 ];
 
 const { spawn } = require("child_process");
@@ -141,12 +135,18 @@ function install() {
       addedPerms++;
     }
   }
-  // 2b. Add or update permission hook in settings (PreToolUse)
+  // 2b. Copy hook to stable location and register in settings (PreToolUse)
   if (fs.existsSync(HOOK_SOURCE)) {
+    // Copy to ~/.crosschat/hooks/ so the path survives package updates
+    const stableDir = path.dirname(STABLE_HOOK);
+    fs.mkdirSync(stableDir, { recursive: true });
+    fs.copyFileSync(HOOK_SOURCE, STABLE_HOOK);
+    fs.chmodSync(STABLE_HOOK, 0o755);
+
     if (!settings.hooks) settings.hooks = {};
     if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
 
-    const hookCommand = HOOK_SOURCE;
+    const hookCommand = STABLE_HOOK;
     const existingIdx = settings.hooks.PreToolUse.findIndex((entry) =>
       entry.hooks &&
       entry.hooks.some((h) => h.command && h.command.includes("permission-hook.sh"))
@@ -303,15 +303,13 @@ async function status() {
   console.log("Dashboard:      http://localhost:" + hubPort);
 
   try {
-    const [peerList, taskList, roomList] = await Promise.all([
+    const [peerList, channelList] = await Promise.all([
       hubGet(hubPort, "/api/peers"),
-      hubGet(hubPort, "/api/tasks"),
-      hubGet(hubPort, "/api/rooms"),
+      hubGet(hubPort, "/api/channels"),
     ]);
 
     const peers = Array.isArray(peerList) ? peerList : [];
-    const tasks = Array.isArray(taskList) ? taskList : [];
-    const roomArr = Array.isArray(roomList) ? roomList : [];
+    const channels = Array.isArray(channelList) ? channelList : [];
 
     console.log("");
     console.log("Agents:         " + peers.length + " connected");
@@ -320,16 +318,7 @@ async function status() {
       console.log("  " + badge + " " + p.name + " — " + (p.cwd || "?"));
     }
 
-    if (tasks.length > 0) {
-      const byStatus = {};
-      for (const t of tasks) {
-        byStatus[t.status] = (byStatus[t.status] || 0) + 1;
-      }
-      const summary = Object.entries(byStatus).map(([k, v]) => v + " " + k).join(", ");
-      console.log("Tasks:          " + tasks.length + " (" + summary + ")");
-    }
-
-    console.log("Rooms:          " + roomArr.length);
+    console.log("Channels:       " + channels.length);
   } catch {
     console.log("");
     console.log("Hub not responding (port " + hubPort + ").");
@@ -456,7 +445,7 @@ async function peers() {
     const detail = p.statusDetail ? " " + p.statusDetail : "";
     console.log("  " + p.name + "  " + badge + detail);
     console.log("    ID:        " + p.peerId);
-    console.log("    Room:      " + (p.currentRoom || "—"));
+    console.log("    Channel:   " + (p.currentChannel || "general"));
     console.log("    Directory: " + (p.cwd || "—"));
     console.log("    Connected: " + (p.connectedAt ? timeAgo(p.connectedAt) : "—"));
     console.log("");
@@ -485,7 +474,7 @@ async function tasks() {
     }[t.status] || t.status.toUpperCase();
     console.log("  [" + statusTag + "] " + t.description);
     console.log("    ID:       " + t.taskId);
-    console.log("    Room:     " + (t.roomId || "—"));
+    console.log("    Channel:  " + (t.channelId || "—"));
     console.log("    Creator:  " + (t.creatorName || "—"));
     if (t.claimantName) {
       console.log("    Assignee: " + t.claimantName);
@@ -498,37 +487,27 @@ async function tasks() {
   }
 }
 
-async function rooms() {
+async function channels() {
   const port = requireHub();
-  const [roomData, peerData] = await Promise.all([
-    hubGet(port, "/api/rooms"),
+  const [channelData, peerData] = await Promise.all([
+    hubGet(port, "/api/channels"),
     hubGet(port, "/api/peers"),
   ]);
-  const roomList = Array.isArray(roomData) ? roomData : [];
+  const channelList = Array.isArray(channelData) ? channelData : [];
   const peerList = Array.isArray(peerData) ? peerData : [];
 
-  if (roomList.length === 0) {
-    console.log("No active rooms.");
+  if (channelList.length === 0) {
+    console.log("No active channels.");
     return;
   }
 
-  // Count peers per room
-  const peersPerRoom = {};
-  for (const p of peerList) {
-    const room = p.currentRoom || "general";
-    if (!peersPerRoom[room]) peersPerRoom[room] = [];
-    peersPerRoom[room].push(p.name);
-  }
-
-  console.log("Rooms (" + roomList.length + "):\n");
-  for (const r of roomList) {
-    const name = r.name || r.id;
-    const msgCount = r.messageCount != null ? r.messageCount : "?";
-    const roomPeers = peersPerRoom[name] || peersPerRoom[r.id] || [];
-    console.log("  " + name);
-    console.log("    Messages: " + msgCount + "  Agents: " + roomPeers.length);
-    if (roomPeers.length > 0) {
-      console.log("    " + roomPeers.join(", "));
+  console.log("Channels (" + channelList.length + "):\n");
+  for (const ch of channelList) {
+    const agentsInChannel = peerList.filter((p) => (p.currentChannel || "general") === ch);
+    console.log("  # " + ch);
+    console.log("    Agents: " + agentsInChannel.length);
+    if (agentsInChannel.length > 0) {
+      console.log("    " + agentsInChannel.map((a) => a.name).join(", "));
     }
     console.log("");
   }
@@ -589,10 +568,10 @@ function showHelp() {
   console.log("  crosschat restart              Restart the hub server");
   console.log("");
   console.log("Info:");
-  console.log("  crosschat status               Overview of hub, agents, tasks, rooms");
+  console.log("  crosschat status               Overview of hub, agents, and channels");
   console.log("  crosschat peers                List connected agents with details");
   console.log("  crosschat tasks [status]       List tasks (optional: open, claimed, completed, failed)");
-  console.log("  crosschat rooms                List active rooms");
+  console.log("  crosschat channels             List active channels");
   console.log("");
   console.log("  crosschat --version            Show version");
   console.log("  crosschat --help               Show this help");
@@ -633,8 +612,9 @@ switch (command) {
   case "tasks":
     tasks();
     break;
+  case "channels":
   case "rooms":
-    rooms();
+    channels();
     break;
   case "--version":
   case "-v":