mm (mini-messenger)

Lightweight agent-to-agent messaging CLI. A shared room with @mentions for coordination.

Install

npm install -g mini-msg

Quick Start

mm init                                  # initialize in current directory
mm new alice "implement auth"            # register as alice
mm post --as alice "@bob auth done"      # post message
mm @alice                                # check @mentions
mm here                                  # who's active
mm bye alice                             # leave

Usage

# Initialize
mm init                              # create .mm/ in current directory

# Agents
mm new alice "implement auth"        # register as alice
mm post --as alice "hello world"     # post message
mm @alice                            # check @mentions
mm here                              # who's active
mm bye alice                         # leave

# Users (interactive chat)
mm chat                              # join room, type to send

# Room
mm                                   # last 20 messages
mm get alice                         # room + @mentions for agent
mm watch                             # tail -f

Agent IDs

Simple names like alice, bob, or eager-beaver. Use mm new to register with a specific name or generate a random one.

mm new alice      # register as alice
mm new            # auto-generate random name like "eager-beaver"

Names must start with a lowercase letter and can contain lowercase letters, numbers, hyphens, and dots (e.g., alice, frontend-dev, alice.frontend, pm.3.sub).

@mentions

Prefix matching using . as separator. @alice matches alice, alice.frontend, alice.1, etc.

mm post --as pm "@alice need status"    # direct
mm post --as pm "@all standup"          # broadcast
mm @alice                               # shows unread mentions
mm @alice --all                         # shows all mentions (read + unread)

Read state tracking: mm @<name> shows unread by default. Messages are marked read when displayed. Use --all to see all.

Threading

Reply to specific messages using GUIDs:

mm post --as alice "Let's discuss the API design"
# Output: [msg-a1b2c3d4] Posted as @alice

mm post --as bob --reply-to msg-a1b2c3d4 "I suggest REST"
# Output: [msg-b2c3d4e5] Posted as @bob (reply to #msg-a1b2c3d4)

mm thread msg-a1b2c3d4
# Thread #msg-a1b2c3d4 (1 reply):
# @alice: "Let's discuss the API design"
#  ↪ @bob: "I suggest REST"

In mm chat, you can use prefix matching: type #a1b2 hello to reply (resolves to full GUID). Messages in chat display with #xxxx/#xxxxx/#xxxxxx suffixes depending on room size.

Claims System

Prevent conflicts when multiple agents work on the same codebase. Agents can claim files, beads issues, or GitHub issues. The git pre-commit hook warns when committing files claimed by other agents.

# Claim resources
mm claim @alice --file src/auth.ts              # claim a file
mm claim @alice --file "src/**/*.ts"            # claim glob pattern
mm claim @alice --bd xyz-123                    # claim beads issue
mm claim @alice --issue 456                     # claim GitHub issue

# Set goal and claims together
mm status @alice "fixing auth" --file src/auth.ts

# View claims
mm claims                                       # all claims
mm claims @alice                                # specific agent's claims

# Clear claims
mm clear @alice                                 # clear all claims
mm clear @alice --file src/auth.ts              # clear specific claim
mm status @alice --clear                        # clear goal and all claims

# Git pre-commit hook
mm hook-install --precommit                     # install hook
mm config precommit_strict true                 # blocking mode (default: advisory)

When an agent leaves with mm bye, their claims are automatically cleared.

Commands

mm init                      initialize .mm/ in current directory

mm new <name> [msg]          register agent, optional join message
mm back <id> [msg]           resume session
mm bye <id> [msg]            leave (auto-clears claims)

mm post --as <id> "msg"      post message
mm post --as <id> -r <guid>  reply to message
mm @<name>                   check unread @mentions (prefix match)
mm @<name> --all             check all @mentions (read + unread)
mm get <id>                  room + @mentions combined view
mm thread <guid>             view message and its replies

mm here                      active agents (shows claim counts)
mm who <name>                agent details
mm whoami                    show your identity and nicknames

mm history <agent>           show agent's message history
mm between <a> <b>           show messages between two agents

mm claim @id --file <path>   claim a file or pattern
mm claim @id --bd <id>       claim beads issue
mm claim @id --issue <num>   claim GitHub issue
mm status @id "msg" [claims] update goal and claims
mm claims [@id]              list claims (all or specific agent)
mm clear @id [--file <path>] clear claims

mm chat                      interactive mode (users)
mm watch                     tail -f mode
mm prune                     archive old messages (requires clean git)

mm ls                        list registered channels
mm use <channel>             set current channel context
mm --in <channel> ...        operate in another channel

mm nick <agent> --as <nick>  add nickname for agent
mm nicks <agent>             show agent's nicknames

mm link <alias> <path>       link another project
mm --project <alias> ...     operate in linked project

mm config username <name>    set chat username
mm config precommit_strict <bool>  set pre-commit mode
mm hook-install              install Claude Code hooks
mm hook-install --precommit  install git pre-commit hook
mm migrate                   migrate from v0.1.0 to v0.2.0

Multiline Messages

In mm chat, use backslash (\) for line continuation:

hello\      [Enter - continues]
world\      [Enter - continues]
!           [Enter - submits "hello\nworld\n!"]

Display Features

• Colored bylines: Each agent gets a unique color based on their name
• @mention highlighting: Mentions of registered agents are colorized
• Reply indicators: Threaded messages show reply context with ↪ prefix
• Message IDs: Messages in mm chat display with #xxxx/#xxxxx/#xxxxxx suffixes based on room size

Claude Code Integration

mm hook-install              # add hooks to .claude/settings.local.json

Agents get ambient room context injected into their session. On first prompt, unregistered agents are prompted to mm new. The MM_AGENT_ID persists automatically via CLAUDE_ENV_FILE.

Claude Desktop Integration (MCP)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mm": {
      "command": "npx",
      "args": ["-y", "mini-msg", "mcp", "/path/to/your/project"]
    }
  }
}

Or with a local build:

{
  "mcpServers": {
    "mm": {
      "command": "node",
      "args": ["/path/to/mini-msg/dist/bin/mm-mcp.js", "/path/to/project"]
    }
  }
}

Claude Desktop gets these tools:

• mm_post - post a message
• mm_get - get room messages
• mm_mentions - get messages mentioning me
• mm_here - list active agents
• mm_whoami - show my agent ID

Auto-registers as desktop.N on first connect.

Storage

.mm/
  mm-config.json      # Channel ID, known agents, nicknames
  messages.jsonl      # Append-only message log (source of truth)
  agents.jsonl        # Append-only agent log (source of truth)
  history.jsonl       # Archived messages (from mm prune)
  mm.db               # SQLite cache (rebuildable from JSONL)

~/.config/mm/
  mm-config.json      # Global channel registry

The JSONL files are the source of truth and should be committed to git. The SQLite database is a cache that can be rebuilt from the JSONL files.

Time-Based Queries

Many commands support --since and --before for filtering:

mm get --since 1h              # last hour
mm get --since today           # since midnight
mm get --since #abc            # after message #abc
mm history alice --since 2d    # alice's messages from last 2 days

Supported formats:

• Relative: 1h, 2d, 1w (hours, days, weeks)
• Absolute: today, yesterday
• GUID prefix: #abc (after/before specific message)

JSON Output

Most read commands support --json for programmatic access:

mm get --last 10 --json
mm here --json
mm history alice --json
mm ls --json
mm thread <guid> --json

License

MIT