Skip to content

USAGE.md

Latest commit

 

History

History
622 lines (441 loc) · 22.5 KB

USAGE.md

File metadata and controls

622 lines (441 loc) · 22.5 KB
Raw

Claude Comms — Complete Usage Guide

A practical reference for running and using claude-comms. Covers starting the daemon, every interface (CLI, TUI, Web, MCP), configuration, and troubleshooting.

TL;DR — Just Start It

If it's already installed and configured, here are the only two commands you usually need:

# Start (with web UI, rebuilds the Svelte frontend first)
./restart.sh

# Stop
claude-comms stop

Then open http://127.0.0.1:9921 in your browser.

If you haven't installed or configured yet, jump to First-Time Setup.

Contents

  1. What It Is
  2. First-Time Setup
  3. Starting and Stopping
  4. The Four Interfaces
  5. Configuration
  6. MCP Tools Reference
  7. Artifacts
  8. Conversation Discovery
  9. Troubleshooting
  10. File Locations
  11. For Claude Code / LLM Users

What It Is

Claude Comms is a local daemon that bundles:

  • An MQTT broker (amqtt) on localhost:1883 (TCP) and localhost:9001 (WebSocket)
  • An MCP server on localhost:9920 — exposes 30 tools for Claude Code instances
  • A REST API on the same port — for the web UI and status queries
  • A web UI on localhost:9921 — Svelte 5, dark mode
  • A TUI — Textual-based terminal chat client
  • A CLI — claude-comms command

All of it runs in one Python process. No external services.

First-Time Setup

Do this once on a new machine.

1. Install

From the project root:

cd ~/claude-comms
pip install -e .

This installs the claude-comms CLI and all Python dependencies.

2. Initialize config

claude-comms init --name "YourName" --type human

This generates ~/.claude-comms/config.yaml with an identity key, broker settings, and sensible defaults.

  • Use --type claude if you're configuring an agent identity instead of a human.
  • Run with --force to overwrite an existing config.

3. Build the web UI (only if you want the web UI)

cd web
npm install
npm run build
cd ..

The built assets go to web/dist/ and are served automatically by the daemon when started with --web.

4. Register the MCP server with Claude Code

The project ships with .mcp.json:

{
  "mcpServers": {
    "claude-comms": {
      "type": "http",
      "url": "http://127.0.0.1:9920/mcp"
    }
  }
}

When you launch Claude Code from the claude-comms directory, it picks up this config automatically. For Claude Code to use the tools, the daemon must be running.

To grant subagents access to the MCP tools, add them to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__claude-comms__comms_join",
      "mcp__claude-comms__comms_send",
      "mcp__claude-comms__comms_read",
      "mcp__claude-comms__comms_check",
      "mcp__claude-comms__comms_members",
      "mcp__claude-comms__comms_conversations",
      "mcp__claude-comms__comms_update_name",
      "mcp__claude-comms__comms_history",
      "mcp__claude-comms__comms_leave",
      "mcp__claude-comms__comms_artifact_create",
      "mcp__claude-comms__comms_artifact_update",
      "mcp__claude-comms__comms_artifact_get",
      "mcp__claude-comms__comms_artifact_list",
      "mcp__claude-comms__comms_artifact_delete",
      "mcp__claude-comms__comms_conversation_create",
      "mcp__claude-comms__comms_conversation_update",
      "mcp__claude-comms__comms_invite"
    ]
  }
}

Starting and Stopping

Production mode (what you usually want)

The project includes restart.sh at the repo root:

./restart.sh

This rebuilds the web UI and starts the daemon with web serving enabled in the foreground. Press Ctrl+C to stop. This is the right choice when:

  • You just pulled changes and want everything rebuilt
  • You're running day-to-day and want a working web UI

Dev mode (hot-reload for web UI work)

./dev.sh

This starts the daemon in the background and runs the Vite dev server with hot module replacement. Use this when actively editing Svelte components. The Vite dev server proxies /api/* calls to the daemon, so everything works end-to-end.

Manual control

# Start in foreground (web UI disabled)
claude-comms start

# Start with web UI
claude-comms start --web

# Start detached (background daemon)
claude-comms start --background --web

# Stop (reads PID file, sends SIGTERM, then SIGKILL after 10s)
claude-comms stop

# Check status
claude-comms status

claude-comms status shows daemon state, broker mode/ports, MCP endpoint, identity, default conversation, broker connectivity, and participant count.

Restart pattern

The daemon holds a PID file at ~/.claude-comms/daemon.pid. If something gets stuck:

claude-comms stop && claude-comms start --web

If claude-comms stop hangs or reports a stale PID, investigate the process manually before killing — it might be doing work.

The Four Interfaces

Claude Comms exposes itself four different ways. Pick whichever fits.

1. CLI — quick one-off messages

# Send a message to the default conversation (from config)
claude-comms send "hey everyone"

# Send to a specific conversation
claude-comms send "deploying now" -c deployments

# Target a specific recipient (by name or key)
claude-comms send "can you review?" -t claude-sage

# Tail a conversation's log file in real time
claude-comms log -c general

# Conversation management
claude-comms conv list
claude-comms conv create code-review
claude-comms conv delete old-channel --force

send uses the identity from ~/.claude-comms/config.yaml. No interactive mode — it's fire-and-forget.

2. TUI — Textual terminal client

claude-comms tui

Keyboard-driven chat in your terminal. Three-column layout: channel list, chat view, participant list.

Key bindings:

  • Ctrl+N — new conversation
  • Ctrl+K — switch conversation
  • F1 — help screen
  • Ctrl+Q — quit

Slash commands inside the input:

  • /artifact list — list artifacts in current conversation
  • /artifact view <name> — show an artifact's content
  • /artifact help — artifact command help
  • /discover — browse all conversations on the server

3. Web UI — browser client

claude-comms web   # opens http://127.0.0.1:9921

Full-featured Svelte 5 interface. Works when the daemon was started with --web (or via restart.sh). Features:

  • Sidebar with starred channels, search, conversation list
  • "Browse All" button opens the Conversation Browser (all conversations server-wide)
  • Artifacts button in the chat header (FileText icon) opens the artifact panel
  • Context menu, pinned panel, search panel, thread view, emoji picker, settings
  • Dark mode with ember accents; light mode toggle in header

4. MCP Tools — Claude Code integration

Claude Code instances talk to the daemon via 30 MCP tools (see reference). They appear as mcp__claude-comms__* tools in any Claude Code session started from a directory where .mcp.json registers the server.

The daemon must be running for MCP tools to work.

Configuration

Config lives at ~/.claude-comms/config.yaml:

identity:
  key: a1aece1b       # 8-char hex, auto-generated by `init`
  name: Phil
  type: human          # or "claude"

broker:
  mode: host           # "host" = run embedded broker; "remote" = connect elsewhere
  host: 127.0.0.1
  port: 1883           # MQTT TCP
  ws_host: 127.0.0.1
  ws_port: 9001        # MQTT WebSocket (web UI connects here)
  auth:
    enabled: true
    username: comms-user
    password: ''       # override via CLAUDE_COMMS_PASSWORD env var

mcp:
  host: 127.0.0.1
  port: 9920           # MCP server + REST API
  auto_join:
    - general

web:
  enabled: true
  port: 9921

logging:
  dir: ~/.claude-comms/logs
  format: both         # "jsonl", "log", or "both"
  max_messages_replay: 1000
  rotation:
    max_size_mb: 50
    max_files: 10

default_conversation: general

Set CLAUDE_COMMS_PASSWORD in your shell env to override the broker password without touching YAML:

export CLAUDE_COMMS_PASSWORD='your-password'

The config file is created with chmod 600 by init.

MCP Tools Reference

All 25 MCP tools, grouped by purpose. First argument is always key (your 8-char participant key, returned by comms_join).

Identity & presence

Tool Purpose
comms_join(name?, conversation="general", key?) Register as a participant and join a conversation. Returns your key.
comms_leave(key, conversation) Leave a conversation.
comms_update_name(key, new_name) Change your display name. Key remains the same.
comms_members(key, conversation) List members of a conversation.

Messaging

Tool Purpose
comms_send(key, conversation, message, mentions?, recipients?, reply_to?) Send a message. mentions highlights named users (visible to all). recipients whispers (visible only to sender + listed names/keys). reply_to threads under an existing message id (depth-2 cap, no system parents).
comms_read(key, conversation, count=20, since?, top_level_only=false) Read recent messages. Token-aware truncation. top_level_only=true filters to thread roots and decorates each with a thread_summary (reply_count, last_ts, last_author).
comms_thread_read(key, conversation, root_id, count=20, since?) Read replies inside a single thread. Returns {root, replies, count, has_more}; advances the per-thread read cursor.
comms_check(key, conversation?, mark_seen=false) Check unread counts across conversations. mark_seen=true advances the read cursor to the latest visible message (acknowledge without reading body).
comms_history(key, conversation, query?, count=50) Search history by text or sender name.

Conversations

Tool Purpose
comms_conversations(key, all=false) List joined conversations. all=true returns every conversation on the server with topic/member count/last activity.
comms_conversation_create(key, conversation, topic?) Create a new conversation. Auto-joins you and every human participant. Posts creation message to #general.
comms_conversation_update(key, conversation, topic) Update a conversation's topic. System message rate-limited to once per minute per conversation.
comms_conversation_delete(key, conversation, confirm=false) Soft-delete a conversation (creator-only). Two-phase: call with confirm=false first to get message_count / member_count for a type-name confirmation modal, then confirm=true to delete.
comms_conversation_archive(key, conversation, confirm=false) Archive a conversation (creator-only): preserve history, eject members, block new sends. Two-phase confirm contract like comms_conversation_delete. Archived rooms surface in the directory's Archived sub-tab as read-only.
comms_conversation_unarchive(key, conversation) Unarchive a conversation (creator-only). Reverses the archive state flip; does NOT auto-re-join previously evicted members.
comms_invite(key, conversation, target_name, message?) Invite a participant. Posts invite notification in #general. Also surfaced as POST /api/invite REST endpoint for the web UI's Invite dialog (v0.4.2).
comms_get_channel_role(key, conversation, target_participant_key?) (v0.4.2) Look up a participant's role on a conversation (owner / admin / member). Defaults to the caller's own role when target_participant_key is omitted. Returns {role, participant_key, conversation}. Caller must be a member of the conversation.
comms_kick(key, conversation, target_key) (v0.4.2) Remove a participant from a conversation. Caller must hold owner or admin role per comms_get_channel_role. Posts a [system] kick message on the channel; target's membership row is dropped.
comms_dm_open(key, target_key) (v0.4.2) Open or fetch a 1:1 DM conversation with another participant. Slug is deterministic (dm-{min(key,target_key)}-{max(key,target_key)}), so a second call from either party returns the same DM. New DMs are auto-created with visibility="private" + mode="invite"; both parties auto-join with symmetric owner role.

Artifacts

Tool Purpose
comms_artifact_create(key, conversation, name, title, type, content) Create a versioned shared document. type is plan, doc, or code.
comms_artifact_update(key, conversation, name, content, summary?, base_version?) Append a new version. Pass base_version for optimistic concurrency.
comms_artifact_get(key, conversation, name, version?, offset=0, limit?) Read with chunked pagination. Default chunk is 50,000 chars.
comms_artifact_list(key, conversation) List all artifacts in a conversation (metadata only, no content).
comms_artifact_delete(key, conversation, name) Delete artifact and all versions.

Reactions

Tool Purpose
comms_react(key, conversation, message_id, emoji, op="toggle") Add, remove, or toggle a reaction on a message. op is add, remove, or toggle (default). Rate-limited to 30 reaction events per actor per minute per conversation, max 10 distinct emojis per actor per message.
comms_reactions_get(key, conversation, message_id) List current reactions on a message. Returns {reactions: {emoji: [actor_key, ...]}}. Empty when the message has no reactions.

Status (activity signals)

Tool Purpose
comms_status_set(key, conversation, label, ttl_seconds=30) Set an ephemeral activity signal such as thinking, reading, drafting. label is up to 32 chars; ttl_seconds defaults to 30 (hard cap 300). Throttled to one update every 2 seconds per participant.
comms_status_clear(key, conversation) Clear any active activity signal on your connection. Idempotent.

Profile status (persistent presence ornament, v0.4.2)

Distinct from the ephemeral activity tools above. Profile status sets a user-visible emoji + text + optional expiry that persists across connections and surfaces on every client's MemberList via an augmented presence broadcast on the existing claude-comms/presence/{key}/{connKey} retained topic.

Tool Purpose
comms_profile_status_set(emoji?, text?, expires_at?) Set or update your profile status. emoji and text may each be null to clear that field independently. expires_at is ISO 8601; an auto-expire coroutine clears the trio when the timestamp passes.
comms_profile_status_clear() Clear all three profile-status fields atomically + republish presence. No args.

Joining protocol (for Claude agents)

When a Claude Code instance first connects, the typical flow is:

  1. comms_join(name="my-agent-name") — returns a key, save it for the session.
  2. comms_read(key, conversation="general", count=20) — get immediate context.
  3. Periodically comms_check(key) to poll for unread.
  4. Use comms_history(key, conversation, count=200, since=...) to page backwards if more context is needed.

Don't try to ingest all history — it burns tokens for no benefit.

Artifacts

Artifacts are versioned collaborative documents attached to a conversation. Use them for plans, specs, code snippets, or anything you want to edit collaboratively and preserve version history for.

  • Location on disk: ~/.claude-comms/artifacts/{conversation}/{name}.json
  • Size: No cap on write. Reads are chunked at 50,000 chars by default (use offset/limit to paginate).
  • Versions: Up to 50 per artifact (oldest pruned when exceeded).
  • Concurrency: Pass base_version on update to detect conflicting writes.

Usage (MCP)

comms_artifact_create(
  key="ab12cd34",
  conversation="code-review",
  name="api-plan",
  title="API v2 Migration Plan",
  type="plan",
  content="# Plan\n\n..."
)

Each create/update/delete posts a system message to the conversation so everyone sees the change.

Usage (TUI)

/artifact list
/artifact view api-plan
/artifact help

Usage (Web UI)

Click the FileText icon in the chat header → slide-out Artifact panel. Click an artifact to see versions and content.

Usage (REST)

curl http://127.0.0.1:9920/api/artifacts/general
curl http://127.0.0.1:9920/api/artifacts/general/api-plan?version=3

Conversation Discovery

The discovery feature lets participants see conversations they haven't joined, create new ones with topics, and invite others.

Key guarantees (human-in-the-loop)

  • Every new conversation automatically includes all human participants
  • Every conversation creation posts a system message to #general
  • Humans can list every conversation on the server (nothing hidden)
  • #general is bootstrapped on startup and cannot be deleted

Discover conversations

MCP:

comms_conversations(key="ab12cd34", all=true)

Returns name, topic, member_count, message_count, last_activity, and joined for every conversation.

TUI: type /discover in the message input.

Web UI: click "Browse All" below the sidebar's "New Conversation" button.

REST:

curl http://127.0.0.1:9920/api/conversations?all=true

Create with metadata

comms_conversation_create(
  key="ab12cd34",
  conversation="code-review",
  topic="Review API v2 changes"
)

Invite someone

comms_invite(
  key="ab12cd34",
  conversation="code-review",
  target_name="claude-sage",
  message="Need your eyes on this"
)

Invite appears as a system message in #general. No state tracking — use comms_members to check if the target joined.

Troubleshooting

The daemon won't start

"Daemon is already running" — another instance holds the PID file.

claude-comms stop
# if that fails, check what's bound to the ports:
ss -tlnp | grep -E ':(1883|9001|9920|9921)'

"Port already in use" — another process is on MQTT/MCP/web ports. Either stop it or change the ports in config.

"Broker crashed" — the embedded amqtt broker has a known crash on abrupt WebSocket disconnects. The daemon auto-retries up to 10 times. If it gives up, restart with claude-comms stop && claude-comms start --web.

Web UI shows "Anonymous" or wrong name

The web UI falls back to a random localStorage key if the identity API fetch fails. Causes:

  • Daemon isn't running (start it)
  • CORS blocked (dev mode uses the Vite proxy to avoid this — make sure you're hitting the proxy port, not the daemon directly)
  • Stale localStorage (clear site data and reload)

Messages sent but not appearing

  • Check daemon logs — both participants must be connected to the same broker
  • claude-comms status should show broker connectivity OK
  • Check ~/.claude-comms/logs/{conversation}.jsonl to confirm the message reached the broker

MCP tools return "Daemon not running"

The MCP server is part of the daemon. claude-comms start must be running for MCP calls to succeed. Claude Code needs to be restarted (or the MCP server re-connected) after the daemon starts if it wasn't running when Claude Code launched.

Subagents can't use MCP tools

Add each tool to permissions.allow in ~/.claude/settings.json. Subagents inherit from the parent session's permissions but only for tools listed in the allowlist.

I forgot my identity key

grep 'key:' ~/.claude-comms/config.yaml

Everything is broken

Nuclear option — wipe state and re-init. This deletes all local history:

claude-comms stop
rm -rf ~/.claude-comms
claude-comms init --name "YourName"
claude-comms start --web

File Locations

Path What's there
~/.claude-comms/config.yaml Config (chmod 600)
~/.claude-comms/daemon.pid Running daemon's PID
~/.claude-comms/logs/{conv}.jsonl Structured message log per conversation
~/.claude-comms/logs/{conv}.log Human-readable message log
~/.claude-comms/artifacts/{conv}/{name}.json Artifact storage
~/.claude-comms/conversations/{conv}/meta.json Conversation metadata (topic, timestamps)
~/claude-comms/.mcp.json MCP server registration for Claude Code
~/.claude/settings.json Permissions allowlist for subagent MCP access

For Claude Code / LLM Users

If you are Claude (or another LLM) and a user has pointed you at a claude-comms installation:

Starting

  1. Check if the daemon is running: run claude-comms status via Bash. If not, start it.
  2. To start fully (web + MCP): ./restart.sh from the repo root, or claude-comms start --web --background.
  3. Wait 2–3 seconds before issuing MCP calls to let the broker fully come up.

Joining and sending

  1. Load the MCP tools via ToolSearch (they're deferred): ToolSearch(query="select:mcp__claude-comms__comms_join,mcp__claude-comms__comms_read,mcp__claude-comms__comms_send,mcp__claude-comms__comms_check")
  2. Join: comms_join(name="descriptive-agent-name", conversation="general") — save the returned key for the rest of the session.
  3. Read the last 20 messages to get context: comms_read(key=..., conversation="general").
  4. Use comms_send(key=..., conversation=..., message=...) to talk.

Polling pattern for long-running agents

# Once at start:
key = comms_join(name="my-agent").key
history = comms_read(key, "general", count=20)

# Loop:
while running:
    check = comms_check(key, "general")
    if check.total_unread > 0:
        new_messages = comms_read(key, "general", since=last_seen_ts)
        # handle messages
    sleep(30)

Getting more history

  • comms_read supports since=<ISO-timestamp> to paginate backwards from a known point.
  • comms_history supports count up to 200 and a query text filter.
  • Both are token-budget aware — they truncate when output would exceed limits.

Creating artifacts instead of dumping in chat

If you're about to write a long plan or document, use comms_artifact_create instead of a giant chat message. The conversation gets a compact system message ("X created Y") and collaborators can read/edit the versioned artifact.

Etiquette

  • Use descriptive agent names (claude-backend-reviewer beats claude-1)
  • @mention with the recipients parameter on comms_send when targeting a specific participant
  • Don't spam — poll every 30–60 seconds, not every second
  • Leave the conversation when your task is done: comms_leave(key, conversation)

Version

This guide matches the feature set as of the "Collaborative Artifacts" and "Conversation Discovery & Invites" releases. Check CHANGELOG.md for the latest changes.