@hasna/conversations 0.0.2 → 0.0.4

package/README.md

@@ -31,10 +31,10 @@ npx @hasna/conversations
 
 ```bash
 # Basic message
-convo send --to claude-code "Hello from codex"
+conversations send --to claude-code "Hello from codex"
 
 # With context
-convo send --to claude-code "Check this branch" \
+conversations send --to claude-code "Check this branch" \
   --from codex \
   --priority high \
   --working-dir /path/to/project \
@@ -42,56 +42,86 @@ convo send --to claude-code "Check this branch" \
   --branch feature/auth
 
 # With metadata
-convo send --to gemini "Deploy ready" --metadata '{"env":"staging"}'
+conversations send --to gemini "Deploy ready" --metadata '{"env":"staging"}'
 ```
 
 ### Read Messages
 
 ```bash
 # Read all messages for an agent
-convo read --to codex
+conversations read --to codex
 
 # Unread only, as JSON
-convo read --to codex --unread --json
+conversations read --to codex --unread --json
 
 # Filter by session
-convo read --session alice-bob-abc123
+conversations read --session alice-bob-abc123
 
 # Read and mark as read
-convo read --to codex --unread --mark-read
+conversations read --to codex --unread --mark-read
 ```
 
 ### Sessions
 
 ```bash
 # List all sessions
-convo sessions
+conversations sessions
 
 # Sessions for a specific agent
-convo sessions --agent claude-code --json
+conversations sessions --agent claude-code --json
 ```
 
 ### Reply
 
 ```bash
 # Reply to a message (auto-resolves session and recipient)
-convo reply --to 42 "Got it, working on it now"
+conversations reply --to 42 "Got it, working on it now"
+```
+
+### Channels
+
+Channels are broadcast spaces — any agent can post, all members can read.
+
+```bash
+# Create a channel
+conversations channel create deployments --description "Deployment notifications"
+
+# List channels
+conversations channel list
+
+# Join a channel
+conversations channel join deployments --from codex
+
+# Send to a channel
+conversations channel send deployments "v1.2 deployed to staging" --from ops
+
+# Read channel messages
+conversations channel read deployments
+
+# Leave a channel
+conversations channel leave deployments --from codex
+
+# List members
+conversations channel members deployments
 ```
 
 ### Mark Read
 
 ```bash
 # Mark specific messages
-convo mark-read 1 2 3 --agent codex
+conversations mark-read 1 2 3 --agent codex
 
 # Mark entire session
-convo mark-read --session abc123 --agent codex
+conversations mark-read --session abc123 --agent codex
+
+# Mark entire channel
+conversations mark-read --channel deployments --agent codex
 ```
 
 ### Status
 
 ```bash
-convo status
+conversations status
 # Conversations Status
 #   DB Path:    ~/.conversations/messages.db
 #   Messages:   47
@@ -102,7 +132,7 @@ convo status
 ### Interactive TUI
 
 ```bash
-convo
+conversations
 ```
 
 Arrow keys to navigate sessions, Enter to open, `n` for new conversation, `q` to quit, Esc to go back.
@@ -112,7 +142,7 @@ Arrow keys to navigate sessions, Enter to open, `n` for new conversation, `q` to
 For native AI agent integration via the Model Context Protocol:
 
 ```bash
-convo mcp
+conversations mcp
 ```
 
 ### Agent Configuration
@@ -135,11 +165,17 @@ Add to your agent's MCP config:
 
 | Tool | Description |
 |------|-------------|
-| `send_message` | Send a message (sender auto-resolved from env) |
+| `send_message` | Send a direct message (sender auto-resolved from env) |
 | `read_messages` | Read messages with filters |
 | `list_sessions` | List conversation sessions |
 | `reply` | Reply to a message by ID |
 | `mark_read` | Mark messages as read |
+| `create_channel` | Create a new channel |
+| `list_channels` | List all channels with member/message counts |
+| `send_to_channel` | Send a message to a channel |
+| `read_channel` | Read messages from a channel |
+| `join_channel` | Join a channel |
+| `leave_channel` | Leave a channel |
 
 ## Programmatic API
 
@@ -149,9 +185,12 @@ import {
   readMessages,
   listSessions,
   startPolling,
+  createChannel,
+  listChannels,
+  joinChannel,
 } from "@hasna/conversations";
 
-// Send a message
+// Send a direct message
 const msg = sendMessage({
   from: "my-agent",
   to: "claude-code",
@@ -166,31 +205,44 @@ const { stop } = startPolling({
   to_agent: "my-agent",
   on_messages: (msgs) => console.log("New:", msgs),
 });
+
+// Channels
+createChannel("deploys", "my-agent", "Deploy notifications");
+joinChannel("deploys", "claude-code");
+sendMessage({
+  from: "my-agent",
+  to: "deploys",
+  content: "v2.0 shipped",
+  channel: "deploys",
+  session_id: "channel:deploys",
+});
+const channelMsgs = readMessages({ channel: "deploys" });
 ```
 
 ## Architecture
 
 ```
-┌─────────────┐    ┌──────────────┐    ┌─────────────┐
-│  Ink TUI    │    │  Headless    │    │  MCP Server  │
-│  `convo`    │    │  `convo send`│    │  `convo mcp` │
-└──────┬──────┘    └──────┬───────┘    └──────┬───────┘
-       │                  │                   │
-       └──────────┬───────┴───────────────────┘
-                  │
-          ┌───────▼────────┐
-          │   Core Library  │
-          │  SQLite WAL     │
-          │  200ms polling  │
-          └────────────────┘
-                  │
-          ~/.conversations/messages.db
+┌──────────────────┐  ┌─────────────────────┐  ┌──────────────────────┐
+│     Ink TUI      │  │      Headless       │  │     MCP Server       │
+│ `conversations`  │  │ `conversations send`│  │ `conversations mcp`  │
+└────────┬─────────┘  └──────────┬──────────┘  └──────────┬───────────┘
+         │                       │                        │
+         └───────────┬───────────┴────────────────────────┘
+                     │
+             ┌───────▼────────┐
+             │  Core Library   │
+             │  SQLite WAL     │
+             │  200ms polling  │
+             └────────────────┘
+                     │
+             ~/.conversations/messages.db
 ```
 
 - **SQLite WAL mode** for concurrent read/write across processes
 - **200ms polling** for near-instant message delivery
 - **Single shared database** at `~/.conversations/messages.db`
 - Sessions derived from messages (no separate table)
+- **Channels** for broadcast messaging (many-to-many)
 
 ## Development
 

package/bin/index.js

@@ -1890,6 +1890,7 @@ function getDb() {
       session_id TEXT NOT NULL,
       from_agent TEXT NOT NULL,
       to_agent TEXT NOT NULL,
+      channel TEXT,
       content TEXT NOT NULL,
       priority TEXT NOT NULL DEFAULT 'normal',
       working_dir TEXT,
@@ -1903,6 +1904,27 @@ function getDb() {
   db.exec("CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_messages_to ON messages(to_agent)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_messages_created ON messages(created_at)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_messages_channel ON messages(channel)");
+  const cols = db.prepare("PRAGMA table_info(messages)").all();
+  if (!cols.some((c) => c.name === "channel")) {
+    db.exec("ALTER TABLE messages ADD COLUMN channel TEXT");
+  }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS channels (
+      name TEXT PRIMARY KEY,
+      description TEXT,
+      created_by TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS channel_members (
+      channel TEXT NOT NULL REFERENCES channels(name),
+      agent TEXT NOT NULL,
+      joined_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
+      PRIMARY KEY (channel, agent)
+    )
+  `);
   return db;
 }
 function closeDb() {
@@ -1927,11 +1949,11 @@ function sendMessage(opts) {
   const sessionId = opts.session_id || `${[opts.from, opts.to].sort().join("-")}-${randomUUID().slice(0, 8)}`;
   const metadata = opts.metadata ? JSON.stringify(opts.metadata) : null;
   const stmt = db2.prepare(`
-    INSERT INTO messages (session_id, from_agent, to_agent, content, priority, working_dir, repository, branch, metadata)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO messages (session_id, from_agent, to_agent, channel, content, priority, working_dir, repository, branch, metadata)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     RETURNING *
   `);
-  const row = stmt.get(sessionId, opts.from, opts.to, opts.content, opts.priority || "normal", opts.working_dir || null, opts.repository || null, opts.branch || null, metadata);
+  const row = stmt.get(sessionId, opts.from, opts.to, opts.channel || null, opts.content, opts.priority || "normal", opts.working_dir || null, opts.repository || null, opts.branch || null, metadata);
   return parseMessage(row);
 }
 function readMessages(opts = {}) {
@@ -1950,6 +1972,10 @@ function readMessages(opts = {}) {
     conditions.push("to_agent = ?");
     params.push(opts.to);
   }
+  if (opts.channel) {
+    conditions.push("channel = ?");
+    params.push(opts.channel);
+  }
   if (opts.since) {
     conditions.push("created_at > ?");
     params.push(opts.since);
@@ -1977,6 +2003,12 @@ function markSessionRead(sessionId, reader) {
   const result = stmt.run(sessionId, reader);
   return result.changes;
 }
+function markChannelRead(channelName, reader) {
+  const db2 = getDb();
+  const stmt = db2.prepare(`UPDATE messages SET read_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE channel = ? AND from_agent != ? AND read_at IS NULL`);
+  const result = stmt.run(channelName, reader);
+  return result.changes;
+}
 function getMessageById(id) {
   const db2 = getDb();
   const row = db2.prepare("SELECT * FROM messages WHERE id = ?").get(id);
@@ -2019,6 +2051,64 @@ var init_sessions = __esm(() => {
   init_db();
 });
 
+// src/lib/channels.ts
+function createChannel(name, createdBy, description) {
+  const db2 = getDb();
+  const row = db2.prepare("INSERT INTO channels (name, description, created_by) VALUES (?, ?, ?) RETURNING *").get(name, description || null, createdBy);
+  db2.prepare("INSERT OR IGNORE INTO channel_members (channel, agent) VALUES (?, ?)").run(name, createdBy);
+  return row;
+}
+function listChannels() {
+  const db2 = getDb();
+  const rows = db2.prepare(`
+    SELECT
+      c.name,
+      c.description,
+      c.created_by,
+      c.created_at,
+      (SELECT COUNT(*) FROM channel_members WHERE channel = c.name) AS member_count,
+      (SELECT COUNT(*) FROM messages WHERE channel = c.name) AS message_count
+    FROM channels c
+    ORDER BY c.name ASC
+  `).all();
+  return rows;
+}
+function getChannel(name) {
+  const db2 = getDb();
+  const row = db2.prepare(`
+    SELECT
+      c.name,
+      c.description,
+      c.created_by,
+      c.created_at,
+      (SELECT COUNT(*) FROM channel_members WHERE channel = c.name) AS member_count,
+      (SELECT COUNT(*) FROM messages WHERE channel = c.name) AS message_count
+    FROM channels c
+    WHERE c.name = ?
+  `).get(name);
+  return row;
+}
+function joinChannel(channelName, agent) {
+  const db2 = getDb();
+  const channel = db2.prepare("SELECT name FROM channels WHERE name = ?").get(channelName);
+  if (!channel)
+    return false;
+  db2.prepare("INSERT OR IGNORE INTO channel_members (channel, agent) VALUES (?, ?)").run(channelName, agent);
+  return true;
+}
+function leaveChannel(channelName, agent) {
+  const db2 = getDb();
+  const result = db2.prepare("DELETE FROM channel_members WHERE channel = ? AND agent = ?").run(channelName, agent);
+  return result.changes > 0;
+}
+function getChannelMembers(channelName) {
+  const db2 = getDb();
+  return db2.prepare("SELECT channel, agent, joined_at FROM channel_members WHERE channel = ? ORDER BY joined_at ASC").all(channelName);
+}
+var init_channels = __esm(() => {
+  init_db();
+});
+
 // src/lib/identity.ts
 function resolveIdentity(explicit) {
   if (explicit)
@@ -30910,13 +31000,14 @@ var init_mcp2 = __esm(() => {
   init_zod();
   init_messages();
   init_sessions();
+  init_channels();
   server = new McpServer({
     name: "conversations",
-    version: "0.0.2"
+    version: "0.0.4"
   });
   server.registerTool("send_message", {
     title: "Send Message",
-    description: "Send a message to another agent. The sender is auto-resolved from CONVERSATIONS_AGENT_ID env var.",
+    description: "Send a direct message to another agent. The sender is auto-resolved from CONVERSATIONS_AGENT_ID env var.",
     inputSchema: {
       to: exports_external.string().describe("Recipient agent ID"),
       content: exports_external.string().describe("Message content"),
@@ -30952,6 +31043,7 @@ var init_mcp2 = __esm(() => {
       session_id: exports_external.string().optional().describe("Filter by session ID"),
       from: exports_external.string().optional().describe("Filter by sender agent ID"),
       to: exports_external.string().optional().describe("Filter by recipient agent ID"),
+      channel: exports_external.string().optional().describe("Filter by channel name"),
       since: exports_external.string().optional().describe("Messages after this ISO timestamp"),
       limit: exports_external.number().optional().describe("Max messages to return"),
       unread_only: exports_external.boolean().optional().describe("Only return unread messages")
@@ -31015,6 +31107,114 @@ var init_mcp2 = __esm(() => {
       content: [{ type: "text", text: JSON.stringify({ marked_read: count }, null, 2) }]
     };
   });
+  server.registerTool("create_channel", {
+    title: "Create Channel",
+    description: "Create a new channel. The creator is auto-joined.",
+    inputSchema: {
+      name: exports_external.string().describe("Channel name (e.g. 'deployments', 'code-review')"),
+      description: exports_external.string().optional().describe("Channel description")
+    }
+  }, async ({ name, description }) => {
+    const agent = resolveIdentity();
+    try {
+      const ch = createChannel(name, agent, description);
+      return {
+        content: [{ type: "text", text: JSON.stringify(ch, null, 2) }]
+      };
+    } catch (e) {
+      if (e.message?.includes("UNIQUE constraint")) {
+        return {
+          content: [{ type: "text", text: `Channel #${name} already exists` }],
+          isError: true
+        };
+      }
+      throw e;
+    }
+  });
+  server.registerTool("list_channels", {
+    title: "List Channels",
+    description: "List all available channels with member and message counts."
+  }, async () => {
+    const channels = listChannels();
+    return {
+      content: [{ type: "text", text: JSON.stringify(channels, null, 2) }]
+    };
+  });
+  server.registerTool("send_to_channel", {
+    title: "Send to Channel",
+    description: "Send a message to a channel. All members can see it.",
+    inputSchema: {
+      channel: exports_external.string().describe("Channel name"),
+      content: exports_external.string().describe("Message content"),
+      priority: exports_external.enum(["low", "normal", "high", "urgent"]).optional().describe("Message priority")
+    }
+  }, async ({ channel, content, priority }) => {
+    const from = resolveIdentity();
+    const ch = getChannel(channel);
+    if (!ch) {
+      return {
+        content: [{ type: "text", text: `Channel #${channel} not found` }],
+        isError: true
+      };
+    }
+    const msg = sendMessage({
+      from,
+      to: channel,
+      content,
+      channel,
+      session_id: `channel:${channel}`,
+      priority
+    });
+    return {
+      content: [{ type: "text", text: JSON.stringify(msg, null, 2) }]
+    };
+  });
+  server.registerTool("read_channel", {
+    title: "Read Channel",
+    description: "Read messages from a channel.",
+    inputSchema: {
+      channel: exports_external.string().describe("Channel name"),
+      since: exports_external.string().optional().describe("Messages after this ISO timestamp"),
+      limit: exports_external.number().optional().describe("Max messages to return")
+    }
+  }, async ({ channel, since, limit }) => {
+    const messages = readMessages({ channel, since, limit });
+    return {
+      content: [{ type: "text", text: JSON.stringify(messages, null, 2) }]
+    };
+  });
+  server.registerTool("join_channel", {
+    title: "Join Channel",
+    description: "Join a channel to receive messages.",
+    inputSchema: {
+      channel: exports_external.string().describe("Channel name to join")
+    }
+  }, async ({ channel }) => {
+    const agent = resolveIdentity();
+    const ok = joinChannel(channel, agent);
+    if (!ok) {
+      return {
+        content: [{ type: "text", text: `Channel #${channel} not found` }],
+        isError: true
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify({ channel, agent, joined: true }, null, 2) }]
+    };
+  });
+  server.registerTool("leave_channel", {
+    title: "Leave Channel",
+    description: "Leave a channel.",
+    inputSchema: {
+      channel: exports_external.string().describe("Channel name to leave")
+    }
+  }, async ({ channel }) => {
+    const agent = resolveIdentity();
+    const left = leaveChannel(channel, agent);
+    return {
+      content: [{ type: "text", text: JSON.stringify({ channel, agent, left }, null, 2) }]
+    };
+  });
   isDirectRun = import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("mcp.js") || process.argv[1]?.endsWith("mcp.ts");
   if (isDirectRun) {
     startMcpServer().catch((error48) => {
@@ -31043,6 +31243,7 @@ var {
 // src/cli/index.tsx
 init_messages();
 init_sessions();
+init_channels();
 init_db();
 import chalk2 from "chalk";
 import { render } from "ink";
@@ -31643,6 +31844,7 @@ function startPolling(opts) {
     const messages = readMessages({
       session_id: opts.session_id,
       to: opts.to_agent,
+      channel: opts.channel,
       since: lastSeen
     });
     if (messages.length > 0) {
@@ -31904,7 +32106,7 @@ function App({ agent }) {
 
 // src/cli/index.tsx
 var program2 = new Command;
-program2.name("convo").description("Real-time CLI messaging for AI agents").version("0.0.2");
+program2.name("conversations").description("Real-time CLI messaging for AI agents").version("0.0.4");
 program2.command("send").description("Send a message to an agent").argument("<message>", "Message content").requiredOption("--to <agent>", "Recipient agent ID").option("--from <agent>", "Sender agent ID").option("--session <id>", "Session ID (auto-generated if omitted)").option("--priority <level>", "Priority: low, normal, high, urgent", "normal").option("--working-dir <path>", "Working directory context").option("--repository <repo>", "Repository context").option("--branch <branch>", "Branch context").option("--metadata <json>", "JSON metadata string").option("--json", "Output as JSON").action((message, opts) => {
   const from = resolveIdentity(opts.from);
   const metadata = opts.metadata ? JSON.parse(opts.metadata) : undefined;
@@ -31926,11 +32128,12 @@ program2.command("send").description("Send a message to an agent").argument("<me
   }
   closeDb();
 });
-program2.command("read").description("Read messages").option("--session <id>", "Filter by session ID").option("--from <agent>", "Filter by sender").option("--to <agent>", "Filter by recipient").option("--since <timestamp>", "Messages after this ISO timestamp").option("--limit <n>", "Max messages to return", parseInt).option("--unread", "Only unread messages").option("--mark-read", "Mark returned messages as read").option("--json", "Output as JSON").action((opts) => {
+program2.command("read").description("Read messages").option("--session <id>", "Filter by session ID").option("--from <agent>", "Filter by sender").option("--to <agent>", "Filter by recipient").option("--channel <name>", "Filter by channel").option("--since <timestamp>", "Messages after this ISO timestamp").option("--limit <n>", "Max messages to return", parseInt).option("--unread", "Only unread messages").option("--mark-read", "Mark returned messages as read").option("--json", "Output as JSON").action((opts) => {
   const messages = readMessages({
     session_id: opts.session,
     from: opts.from,
     to: opts.to,
+    channel: opts.channel,
     since: opts.since,
     limit: opts.limit,
     unread_only: opts.unread
@@ -31949,7 +32152,7 @@ program2.command("read").description("Read messages").option("--session <id>", "
       for (const msg of messages) {
         const time3 = chalk2.dim(msg.created_at.slice(11, 19));
         const from = chalk2.cyan(msg.from_agent);
-        const to = chalk2.yellow(msg.to_agent);
+        const to = msg.channel ? chalk2.magenta(`#${msg.channel}`) : chalk2.yellow(msg.to_agent);
         const priority = msg.priority !== "normal" ? chalk2.red(` [${msg.priority}]`) : "";
         const unread = !msg.read_at ? chalk2.green(" *") : "";
         console.log(`${time3} ${from} \u2192 ${to}${priority}${unread}: ${msg.content}`);
@@ -31996,15 +32199,17 @@ program2.command("reply").description("Reply to a message (uses same session)").
   }
   closeDb();
 });
-program2.command("mark-read").description("Mark messages as read").argument("[ids...]", "Message IDs to mark as read").option("--session <id>", "Mark all messages in session as read").option("--agent <id>", "Agent marking messages as read").option("--json", "Output as JSON").action((ids, opts) => {
+program2.command("mark-read").description("Mark messages as read").argument("[ids...]", "Message IDs to mark as read").option("--session <id>", "Mark all messages in session as read").option("--channel <name>", "Mark all messages in channel as read").option("--agent <id>", "Agent marking messages as read").option("--json", "Output as JSON").action((ids, opts) => {
   const agent = resolveIdentity(opts.agent);
   let count = 0;
   if (opts.session) {
     count = markSessionRead(opts.session, agent);
+  } else if (opts.channel) {
+    count = markChannelRead(opts.channel, agent);
   } else if (ids.length > 0) {
     count = markRead(ids.map(Number), agent);
   } else {
-    console.error(chalk2.red("Provide message IDs or --session flag."));
+    console.error(chalk2.red("Provide message IDs, --session, or --channel flag."));
     process.exit(1);
   }
   if (opts.json) {
@@ -32020,10 +32225,12 @@ program2.command("status").description("Show database stats").option("--json", "
   const totalMessages = db2.prepare("SELECT COUNT(*) as count FROM messages").get().count;
   const totalSessions = db2.prepare("SELECT COUNT(DISTINCT session_id) as count FROM messages").get().count;
   const totalUnread = db2.prepare("SELECT COUNT(*) as count FROM messages WHERE read_at IS NULL").get().count;
+  const totalChannels = db2.prepare("SELECT COUNT(*) as count FROM channels").get().count;
   const stats = {
     db_path: dbPath,
     total_messages: totalMessages,
     total_sessions: totalSessions,
+    total_channels: totalChannels,
     unread_messages: totalUnread
   };
   if (opts.json) {
@@ -32033,10 +32240,134 @@ program2.command("status").description("Show database stats").option("--json", "
     console.log(`  DB Path:    ${stats.db_path}`);
     console.log(`  Messages:   ${stats.total_messages}`);
     console.log(`  Sessions:   ${stats.total_sessions}`);
+    console.log(`  Channels:   ${stats.total_channels}`);
     console.log(`  Unread:     ${stats.unread_messages}`);
   }
   closeDb();
 });
+var channel = program2.command("channel").description("Manage channels");
+channel.command("create").description("Create a new channel").argument("<name>", "Channel name").option("--description <text>", "Channel description").option("--from <agent>", "Creator agent ID").option("--json", "Output as JSON").action((name, opts) => {
+  const agent = resolveIdentity(opts.from);
+  try {
+    const ch = createChannel(name, agent, opts.description);
+    if (opts.json) {
+      console.log(JSON.stringify(ch, null, 2));
+    } else {
+      console.log(chalk2.green(`Channel #${ch.name} created`) + (ch.description ? chalk2.dim(` \u2014 ${ch.description}`) : ""));
+    }
+  } catch (e) {
+    if (e.message?.includes("UNIQUE constraint")) {
+      console.error(chalk2.red(`Channel #${name} already exists.`));
+      process.exit(1);
+    }
+    throw e;
+  }
+  closeDb();
+});
+channel.command("list").description("List all channels").option("--json", "Output as JSON").action((opts) => {
+  const channels = listChannels();
+  if (opts.json) {
+    console.log(JSON.stringify(channels, null, 2));
+  } else {
+    if (channels.length === 0) {
+      console.log(chalk2.dim("No channels found."));
+    } else {
+      for (const ch of channels) {
+        const desc = ch.description ? chalk2.dim(` \u2014 ${ch.description}`) : "";
+        console.log(`${chalk2.magenta(`#${ch.name}`)}${desc}  ${ch.member_count} members, ${ch.message_count} messages`);
+      }
+    }
+  }
+  closeDb();
+});
+channel.command("send").description("Send a message to a channel").argument("<channel>", "Channel name").argument("<message>", "Message content").option("--from <agent>", "Sender agent ID").option("--priority <level>", "Priority: low, normal, high, urgent", "normal").option("--json", "Output as JSON").action((channelName, message, opts) => {
+  const from = resolveIdentity(opts.from);
+  const ch = getChannel(channelName);
+  if (!ch) {
+    console.error(chalk2.red(`Channel #${channelName} not found.`));
+    process.exit(1);
+  }
+  const msg = sendMessage({
+    from,
+    to: channelName,
+    content: message,
+    channel: channelName,
+    session_id: `channel:${channelName}`,
+    priority: opts.priority
+  });
+  if (opts.json) {
+    console.log(JSON.stringify(msg, null, 2));
+  } else {
+    console.log(chalk2.green(`Message sent to #${channelName}`) + chalk2.dim(` (id: ${msg.id})`));
+  }
+  closeDb();
+});
+channel.command("read").description("Read messages from a channel").argument("<channel>", "Channel name").option("--since <timestamp>", "Messages after this ISO timestamp").option("--limit <n>", "Max messages to return", parseInt).option("--json", "Output as JSON").action((channelName, opts) => {
+  const messages = readMessages({
+    channel: channelName,
+    since: opts.since,
+    limit: opts.limit
+  });
+  if (opts.json) {
+    console.log(JSON.stringify(messages, null, 2));
+  } else {
+    if (messages.length === 0) {
+      console.log(chalk2.dim(`No messages in #${channelName}.`));
+    } else {
+      for (const msg of messages) {
+        const time3 = chalk2.dim(msg.created_at.slice(11, 19));
+        const from = chalk2.cyan(msg.from_agent);
+        const priority = msg.priority !== "normal" ? chalk2.red(` [${msg.priority}]`) : "";
+        console.log(`${time3} ${from} \u2192 ${chalk2.magenta(`#${channelName}`)}${priority}: ${msg.content}`);
+      }
+    }
+  }
+  closeDb();
+});
+channel.command("join").description("Join a channel").argument("<channel>", "Channel name").option("--from <agent>", "Agent ID").option("--json", "Output as JSON").action((channelName, opts) => {
+  const agent = resolveIdentity(opts.from);
+  const ok = joinChannel(channelName, agent);
+  if (!ok) {
+    console.error(chalk2.red(`Channel #${channelName} not found.`));
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify({ channel: channelName, agent, joined: true }));
+  } else {
+    console.log(chalk2.green(`${agent} joined #${channelName}`));
+  }
+  closeDb();
+});
+channel.command("leave").description("Leave a channel").argument("<channel>", "Channel name").option("--from <agent>", "Agent ID").option("--json", "Output as JSON").action((channelName, opts) => {
+  const agent = resolveIdentity(opts.from);
+  const ok = leaveChannel(channelName, agent);
+  if (opts.json) {
+    console.log(JSON.stringify({ channel: channelName, agent, left: ok }));
+  } else {
+    if (ok) {
+      console.log(chalk2.green(`${agent} left #${channelName}`));
+    } else {
+      console.log(chalk2.dim(`${agent} was not a member of #${channelName}`));
+    }
+  }
+  closeDb();
+});
+channel.command("members").description("List channel members").argument("<channel>", "Channel name").option("--json", "Output as JSON").action((channelName, opts) => {
+  const members = getChannelMembers(channelName);
+  if (opts.json) {
+    console.log(JSON.stringify(members, null, 2));
+  } else {
+    if (members.length === 0) {
+      console.log(chalk2.dim(`No members in #${channelName}.`));
+    } else {
+      console.log(chalk2.magenta(`#${channelName}`) + chalk2.dim(` \u2014 ${members.length} member(s)`));
+      for (const m of members) {
+        console.log(`  ${chalk2.cyan(m.agent)} ${chalk2.dim(`joined ${m.joined_at.slice(0, 10)}`)}`);
+      }
+    }
+  }
+  closeDb();
+});
 program2.command("mcp").description("Start MCP server").action(async () => {
   const { startMcpServer: startMcpServer2 } = await Promise.resolve().then(() => (init_mcp2(), exports_mcp));
   await startMcpServer2();

package/bin/mcp.js

@@ -28339,6 +28339,7 @@ function getDb() {
       session_id TEXT NOT NULL,
       from_agent TEXT NOT NULL,
       to_agent TEXT NOT NULL,
+      channel TEXT,
       content TEXT NOT NULL,
       priority TEXT NOT NULL DEFAULT 'normal',
       working_dir TEXT,
@@ -28352,6 +28353,27 @@ function getDb() {
   db.exec("CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_messages_to ON messages(to_agent)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_messages_created ON messages(created_at)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_messages_channel ON messages(channel)");
+  const cols = db.prepare("PRAGMA table_info(messages)").all();
+  if (!cols.some((c) => c.name === "channel")) {
+    db.exec("ALTER TABLE messages ADD COLUMN channel TEXT");
+  }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS channels (
+      name TEXT PRIMARY KEY,
+      description TEXT,
+      created_by TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS channel_members (
+      channel TEXT NOT NULL REFERENCES channels(name),
+      agent TEXT NOT NULL,
+      joined_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
+      PRIMARY KEY (channel, agent)
+    )
+  `);
   return db;
 }
 
@@ -28368,11 +28390,11 @@ function sendMessage(opts) {
   const sessionId = opts.session_id || `${[opts.from, opts.to].sort().join("-")}-${randomUUID().slice(0, 8)}`;
   const metadata = opts.metadata ? JSON.stringify(opts.metadata) : null;
   const stmt = db2.prepare(`
-    INSERT INTO messages (session_id, from_agent, to_agent, content, priority, working_dir, repository, branch, metadata)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO messages (session_id, from_agent, to_agent, channel, content, priority, working_dir, repository, branch, metadata)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     RETURNING *
   `);
-  const row = stmt.get(sessionId, opts.from, opts.to, opts.content, opts.priority || "normal", opts.working_dir || null, opts.repository || null, opts.branch || null, metadata);
+  const row = stmt.get(sessionId, opts.from, opts.to, opts.channel || null, opts.content, opts.priority || "normal", opts.working_dir || null, opts.repository || null, opts.branch || null, metadata);
   return parseMessage(row);
 }
 function readMessages(opts = {}) {
@@ -28391,6 +28413,10 @@ function readMessages(opts = {}) {
     conditions.push("to_agent = ?");
     params.push(opts.to);
   }
+  if (opts.channel) {
+    conditions.push("channel = ?");
+    params.push(opts.channel);
+  }
   if (opts.since) {
     conditions.push("created_at > ?");
     params.push(opts.since);
@@ -28448,6 +28474,57 @@ function listSessions(agent) {
   });
 }
 
+// src/lib/channels.ts
+function createChannel(name, createdBy, description) {
+  const db2 = getDb();
+  const row = db2.prepare("INSERT INTO channels (name, description, created_by) VALUES (?, ?, ?) RETURNING *").get(name, description || null, createdBy);
+  db2.prepare("INSERT OR IGNORE INTO channel_members (channel, agent) VALUES (?, ?)").run(name, createdBy);
+  return row;
+}
+function listChannels() {
+  const db2 = getDb();
+  const rows = db2.prepare(`
+    SELECT
+      c.name,
+      c.description,
+      c.created_by,
+      c.created_at,
+      (SELECT COUNT(*) FROM channel_members WHERE channel = c.name) AS member_count,
+      (SELECT COUNT(*) FROM messages WHERE channel = c.name) AS message_count
+    FROM channels c
+    ORDER BY c.name ASC
+  `).all();
+  return rows;
+}
+function getChannel(name) {
+  const db2 = getDb();
+  const row = db2.prepare(`
+    SELECT
+      c.name,
+      c.description,
+      c.created_by,
+      c.created_at,
+      (SELECT COUNT(*) FROM channel_members WHERE channel = c.name) AS member_count,
+      (SELECT COUNT(*) FROM messages WHERE channel = c.name) AS message_count
+    FROM channels c
+    WHERE c.name = ?
+  `).get(name);
+  return row;
+}
+function joinChannel(channelName, agent) {
+  const db2 = getDb();
+  const channel = db2.prepare("SELECT name FROM channels WHERE name = ?").get(channelName);
+  if (!channel)
+    return false;
+  db2.prepare("INSERT OR IGNORE INTO channel_members (channel, agent) VALUES (?, ?)").run(channelName, agent);
+  return true;
+}
+function leaveChannel(channelName, agent) {
+  const db2 = getDb();
+  const result = db2.prepare("DELETE FROM channel_members WHERE channel = ? AND agent = ?").run(channelName, agent);
+  return result.changes > 0;
+}
+
 // src/lib/identity.ts
 function resolveIdentity(explicit) {
   if (explicit)
@@ -28460,11 +28537,11 @@ function resolveIdentity(explicit) {
 // src/mcp/index.ts
 var server = new McpServer({
   name: "conversations",
-  version: "0.0.2"
+  version: "0.0.4"
 });
 server.registerTool("send_message", {
   title: "Send Message",
-  description: "Send a message to another agent. The sender is auto-resolved from CONVERSATIONS_AGENT_ID env var.",
+  description: "Send a direct message to another agent. The sender is auto-resolved from CONVERSATIONS_AGENT_ID env var.",
   inputSchema: {
     to: exports_external.string().describe("Recipient agent ID"),
     content: exports_external.string().describe("Message content"),
@@ -28500,6 +28577,7 @@ server.registerTool("read_messages", {
     session_id: exports_external.string().optional().describe("Filter by session ID"),
     from: exports_external.string().optional().describe("Filter by sender agent ID"),
     to: exports_external.string().optional().describe("Filter by recipient agent ID"),
+    channel: exports_external.string().optional().describe("Filter by channel name"),
     since: exports_external.string().optional().describe("Messages after this ISO timestamp"),
     limit: exports_external.number().optional().describe("Max messages to return"),
     unread_only: exports_external.boolean().optional().describe("Only return unread messages")
@@ -28563,6 +28641,114 @@ server.registerTool("mark_read", {
     content: [{ type: "text", text: JSON.stringify({ marked_read: count }, null, 2) }]
   };
 });
+server.registerTool("create_channel", {
+  title: "Create Channel",
+  description: "Create a new channel. The creator is auto-joined.",
+  inputSchema: {
+    name: exports_external.string().describe("Channel name (e.g. 'deployments', 'code-review')"),
+    description: exports_external.string().optional().describe("Channel description")
+  }
+}, async ({ name, description }) => {
+  const agent = resolveIdentity();
+  try {
+    const ch = createChannel(name, agent, description);
+    return {
+      content: [{ type: "text", text: JSON.stringify(ch, null, 2) }]
+    };
+  } catch (e) {
+    if (e.message?.includes("UNIQUE constraint")) {
+      return {
+        content: [{ type: "text", text: `Channel #${name} already exists` }],
+        isError: true
+      };
+    }
+    throw e;
+  }
+});
+server.registerTool("list_channels", {
+  title: "List Channels",
+  description: "List all available channels with member and message counts."
+}, async () => {
+  const channels = listChannels();
+  return {
+    content: [{ type: "text", text: JSON.stringify(channels, null, 2) }]
+  };
+});
+server.registerTool("send_to_channel", {
+  title: "Send to Channel",
+  description: "Send a message to a channel. All members can see it.",
+  inputSchema: {
+    channel: exports_external.string().describe("Channel name"),
+    content: exports_external.string().describe("Message content"),
+    priority: exports_external.enum(["low", "normal", "high", "urgent"]).optional().describe("Message priority")
+  }
+}, async ({ channel, content, priority }) => {
+  const from = resolveIdentity();
+  const ch = getChannel(channel);
+  if (!ch) {
+    return {
+      content: [{ type: "text", text: `Channel #${channel} not found` }],
+      isError: true
+    };
+  }
+  const msg = sendMessage({
+    from,
+    to: channel,
+    content,
+    channel,
+    session_id: `channel:${channel}`,
+    priority
+  });
+  return {
+    content: [{ type: "text", text: JSON.stringify(msg, null, 2) }]
+  };
+});
+server.registerTool("read_channel", {
+  title: "Read Channel",
+  description: "Read messages from a channel.",
+  inputSchema: {
+    channel: exports_external.string().describe("Channel name"),
+    since: exports_external.string().optional().describe("Messages after this ISO timestamp"),
+    limit: exports_external.number().optional().describe("Max messages to return")
+  }
+}, async ({ channel, since, limit }) => {
+  const messages = readMessages({ channel, since, limit });
+  return {
+    content: [{ type: "text", text: JSON.stringify(messages, null, 2) }]
+  };
+});
+server.registerTool("join_channel", {
+  title: "Join Channel",
+  description: "Join a channel to receive messages.",
+  inputSchema: {
+    channel: exports_external.string().describe("Channel name to join")
+  }
+}, async ({ channel }) => {
+  const agent = resolveIdentity();
+  const ok = joinChannel(channel, agent);
+  if (!ok) {
+    return {
+      content: [{ type: "text", text: `Channel #${channel} not found` }],
+      isError: true
+    };
+  }
+  return {
+    content: [{ type: "text", text: JSON.stringify({ channel, agent, joined: true }, null, 2) }]
+  };
+});
+server.registerTool("leave_channel", {
+  title: "Leave Channel",
+  description: "Leave a channel.",
+  inputSchema: {
+    channel: exports_external.string().describe("Channel name to leave")
+  }
+}, async ({ channel }) => {
+  const agent = resolveIdentity();
+  const left = leaveChannel(channel, agent);
+  return {
+    content: [{ type: "text", text: JSON.stringify({ channel, agent, left }, null, 2) }]
+  };
+});
 async function startMcpServer() {
   const transport = new StdioServerTransport;
   await server.connect(transport);

package/dist/index.d.ts

@@ -2,15 +2,17 @@
  * @hasna/conversations - Real-time CLI messaging for AI agents
  *
  * Send and receive messages between AI agents on the same machine:
- *   convo send --to claude-code "hello from codex"
- *   convo read --to codex --json
+ *   conversations send --to claude-code "hello from codex"
+ *   conversations read --to codex --json
+ *   conversations channel send deployments "v1.2 deployed"
  *
  * Or use the interactive TUI:
- *   convo
+ *   conversations
  */
-export { sendMessage, readMessages, markRead, markSessionRead, getMessageById, } from "./lib/messages.js";
+export { sendMessage, readMessages, markRead, markSessionRead, markChannelRead, getMessageById, } from "./lib/messages.js";
 export { listSessions, getSession, } from "./lib/sessions.js";
+export { createChannel, listChannels, getChannel, joinChannel, leaveChannel, getChannelMembers, isChannelMember, } from "./lib/channels.js";
 export { getDb, getDbPath, closeDb, } from "./lib/db.js";
-export { startPolling, } from "./lib/poll.js";
+export { startPolling, useChannelMessages, } from "./lib/poll.js";
 export { resolveIdentity, requireIdentity, } from "./lib/identity.js";
-export type { Message, Session, Priority, SendMessageOptions, ReadMessagesOptions, } from "./types.js";
+export type { Message, Session, Channel, ChannelInfo, ChannelMember, Priority, SendMessageOptions, ReadMessagesOptions, } from "./types.js";

package/dist/index.js

@@ -1851,6 +1851,7 @@ function getDb() {
       session_id TEXT NOT NULL,
       from_agent TEXT NOT NULL,
       to_agent TEXT NOT NULL,
+      channel TEXT,
       content TEXT NOT NULL,
       priority TEXT NOT NULL DEFAULT 'normal',
       working_dir TEXT,
@@ -1864,6 +1865,27 @@ function getDb() {
   db.exec("CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_messages_to ON messages(to_agent)");
   db.exec("CREATE INDEX IF NOT EXISTS idx_messages_created ON messages(created_at)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_messages_channel ON messages(channel)");
+  const cols = db.prepare("PRAGMA table_info(messages)").all();
+  if (!cols.some((c) => c.name === "channel")) {
+    db.exec("ALTER TABLE messages ADD COLUMN channel TEXT");
+  }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS channels (
+      name TEXT PRIMARY KEY,
+      description TEXT,
+      created_by TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    )
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS channel_members (
+      channel TEXT NOT NULL REFERENCES channels(name),
+      agent TEXT NOT NULL,
+      joined_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now')),
+      PRIMARY KEY (channel, agent)
+    )
+  `);
   return db;
 }
 function closeDb() {
@@ -1886,11 +1908,11 @@ function sendMessage(opts) {
   const sessionId = opts.session_id || `${[opts.from, opts.to].sort().join("-")}-${randomUUID().slice(0, 8)}`;
   const metadata = opts.metadata ? JSON.stringify(opts.metadata) : null;
   const stmt = db2.prepare(`
-    INSERT INTO messages (session_id, from_agent, to_agent, content, priority, working_dir, repository, branch, metadata)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    INSERT INTO messages (session_id, from_agent, to_agent, channel, content, priority, working_dir, repository, branch, metadata)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     RETURNING *
   `);
-  const row = stmt.get(sessionId, opts.from, opts.to, opts.content, opts.priority || "normal", opts.working_dir || null, opts.repository || null, opts.branch || null, metadata);
+  const row = stmt.get(sessionId, opts.from, opts.to, opts.channel || null, opts.content, opts.priority || "normal", opts.working_dir || null, opts.repository || null, opts.branch || null, metadata);
   return parseMessage(row);
 }
 function readMessages(opts = {}) {
@@ -1909,6 +1931,10 @@ function readMessages(opts = {}) {
     conditions.push("to_agent = ?");
     params.push(opts.to);
   }
+  if (opts.channel) {
+    conditions.push("channel = ?");
+    params.push(opts.channel);
+  }
   if (opts.since) {
     conditions.push("created_at > ?");
     params.push(opts.since);
@@ -1936,6 +1962,12 @@ function markSessionRead(sessionId, reader) {
   const result = stmt.run(sessionId, reader);
   return result.changes;
 }
+function markChannelRead(channelName, reader) {
+  const db2 = getDb();
+  const stmt = db2.prepare(`UPDATE messages SET read_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE channel = ? AND from_agent != ? AND read_at IS NULL`);
+  const result = stmt.run(channelName, reader);
+  return result.changes;
+}
 function getMessageById(id) {
   const db2 = getDb();
   const row = db2.prepare("SELECT * FROM messages WHERE id = ?").get(id);
@@ -1995,6 +2027,65 @@ function getSession(sessionId) {
     unread_count: row.unread_count
   };
 }
+// src/lib/channels.ts
+function createChannel(name, createdBy, description) {
+  const db2 = getDb();
+  const row = db2.prepare("INSERT INTO channels (name, description, created_by) VALUES (?, ?, ?) RETURNING *").get(name, description || null, createdBy);
+  db2.prepare("INSERT OR IGNORE INTO channel_members (channel, agent) VALUES (?, ?)").run(name, createdBy);
+  return row;
+}
+function listChannels() {
+  const db2 = getDb();
+  const rows = db2.prepare(`
+    SELECT
+      c.name,
+      c.description,
+      c.created_by,
+      c.created_at,
+      (SELECT COUNT(*) FROM channel_members WHERE channel = c.name) AS member_count,
+      (SELECT COUNT(*) FROM messages WHERE channel = c.name) AS message_count
+    FROM channels c
+    ORDER BY c.name ASC
+  `).all();
+  return rows;
+}
+function getChannel(name) {
+  const db2 = getDb();
+  const row = db2.prepare(`
+    SELECT
+      c.name,
+      c.description,
+      c.created_by,
+      c.created_at,
+      (SELECT COUNT(*) FROM channel_members WHERE channel = c.name) AS member_count,
+      (SELECT COUNT(*) FROM messages WHERE channel = c.name) AS message_count
+    FROM channels c
+    WHERE c.name = ?
+  `).get(name);
+  return row;
+}
+function joinChannel(channelName, agent) {
+  const db2 = getDb();
+  const channel = db2.prepare("SELECT name FROM channels WHERE name = ?").get(channelName);
+  if (!channel)
+    return false;
+  db2.prepare("INSERT OR IGNORE INTO channel_members (channel, agent) VALUES (?, ?)").run(channelName, agent);
+  return true;
+}
+function leaveChannel(channelName, agent) {
+  const db2 = getDb();
+  const result = db2.prepare("DELETE FROM channel_members WHERE channel = ? AND agent = ?").run(channelName, agent);
+  return result.changes > 0;
+}
+function getChannelMembers(channelName) {
+  const db2 = getDb();
+  return db2.prepare("SELECT channel, agent, joined_at FROM channel_members WHERE channel = ? ORDER BY joined_at ASC").all(channelName);
+}
+function isChannelMember(channelName, agent) {
+  const db2 = getDb();
+  const row = db2.prepare("SELECT 1 FROM channel_members WHERE channel = ? AND agent = ?").get(channelName, agent);
+  return !!row;
+}
 // src/lib/poll.ts
 var import_react = __toESM(require_react(), 1);
 function startPolling(opts) {
@@ -2007,6 +2098,7 @@ function startPolling(opts) {
     const messages = readMessages({
       session_id: opts.session_id,
       to: opts.to_agent,
+      channel: opts.channel,
       since: lastSeen
     });
     if (messages.length > 0) {
@@ -2022,6 +2114,26 @@ function startPolling(opts) {
     }
   };
 }
+function useChannelMessages(channelName) {
+  const [messages, setMessages] = import_react.useState([]);
+  const initialLoad = import_react.useRef(false);
+  import_react.useEffect(() => {
+    if (!initialLoad.current) {
+      const existing = readMessages({ channel: channelName });
+      setMessages(existing);
+      initialLoad.current = true;
+    }
+    const { stop } = startPolling({
+      channel: channelName,
+      interval_ms: 200,
+      on_messages: (newMessages) => {
+        setMessages((prev) => [...prev, ...newMessages]);
+      }
+    });
+    return stop;
+  }, [channelName]);
+  return messages;
+}
 // src/lib/identity.ts
 function resolveIdentity(explicit) {
   if (explicit)
@@ -2038,6 +2150,7 @@ function requireIdentity(explicit) {
   throw new Error("Agent identity required. Set CONVERSATIONS_AGENT_ID env var or pass --from flag.");
 }
 export {
+  useChannelMessages,
   startPolling,
   sendMessage,
   resolveIdentity,
@@ -2045,10 +2158,18 @@ export {
   readMessages,
   markSessionRead,
   markRead,
+  markChannelRead,
   listSessions,
+  listChannels,
+  leaveChannel,
+  joinChannel,
+  isChannelMember,
   getSession,
   getMessageById,
   getDbPath,
   getDb,
+  getChannelMembers,
+  getChannel,
+  createChannel,
   closeDb
 };

package/dist/lib/channels.d.ts

@@ -0,0 +1,8 @@
+import type { Channel, ChannelInfo, ChannelMember } from "../types.js";
+export declare function createChannel(name: string, createdBy: string, description?: string): Channel;
+export declare function listChannels(): ChannelInfo[];
+export declare function getChannel(name: string): ChannelInfo | null;
+export declare function joinChannel(channelName: string, agent: string): boolean;
+export declare function leaveChannel(channelName: string, agent: string): boolean;
+export declare function getChannelMembers(channelName: string): ChannelMember[];
+export declare function isChannelMember(channelName: string, agent: string): boolean;

package/dist/lib/messages.d.ts

@@ -3,4 +3,5 @@ export declare function sendMessage(opts: SendMessageOptions): Message;
 export declare function readMessages(opts?: ReadMessagesOptions): Message[];
 export declare function markRead(ids: number[], reader: string): number;
 export declare function markSessionRead(sessionId: string, reader: string): number;
+export declare function markChannelRead(channelName: string, reader: string): number;
 export declare function getMessageById(id: number): Message | null;

package/dist/lib/poll.d.ts

@@ -2,6 +2,7 @@ import type { Message } from "../types.js";
 export interface PollOptions {
     session_id?: string;
     to_agent?: string;
+    channel?: string;
     interval_ms?: number;
     on_messages: (messages: Message[]) => void;
 }
@@ -15,3 +16,7 @@ export declare function startPolling(opts: PollOptions): {
  * React hook for polling messages in a session.
  */
 export declare function useMessages(sessionId: string, agent?: string): Message[];
+/**
+ * React hook for polling messages in a channel.
+ */
+export declare function useChannelMessages(channelName: string): Message[];

package/dist/mcp/index.d.ts

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
 /**
  * MCP server for conversations.
- * Exposes tools for sending, reading, and managing messages between agents.
+ * Exposes tools for sending, reading, and managing messages and channels between agents.
  *
  * Usage:
- *   convo mcp          # Start MCP server on stdio
- *   convo-mcp          # Direct binary
+ *   conversations mcp          # Start MCP server on stdio
+ *   conversations-mcp          # Direct binary
  */
 export declare function startMcpServer(): Promise<void>;

package/dist/types.d.ts

@@ -4,6 +4,7 @@ export interface Message {
     session_id: string;
     from_agent: string;
     to_agent: string;
+    channel: string | null;
     content: string;
     priority: Priority;
     working_dir: string | null;
@@ -20,11 +21,27 @@ export interface Session {
     message_count: number;
     unread_count: number;
 }
+export interface Channel {
+    name: string;
+    description: string | null;
+    created_by: string;
+    created_at: string;
+}
+export interface ChannelMember {
+    channel: string;
+    agent: string;
+    joined_at: string;
+}
+export interface ChannelInfo extends Channel {
+    member_count: number;
+    message_count: number;
+}
 export interface SendMessageOptions {
     from: string;
     to: string;
     content: string;
     session_id?: string;
+    channel?: string;
     priority?: Priority;
     working_dir?: string;
     repository?: string;
@@ -35,6 +52,7 @@ export interface ReadMessagesOptions {
     session_id?: string;
     from?: string;
     to?: string;
+    channel?: string;
     since?: string;
     limit?: number;
     unread_only?: boolean;

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@hasna/conversations",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Real-time CLI messaging for AI agents",
   "type": "module",
   "bin": {
-    "convo": "./bin/index.js",
-    "convo-mcp": "./bin/mcp.js"
+    "conversations": "bin/index.js",
+    "conversations-mcp": "bin/mcp.js"
   },
   "exports": {
     ".": {