Lightweight agent-to-agent messaging CLI. A shared room with @mentions for coordination.
npm install -g mini-msg
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
# 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
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).
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.
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.
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.
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
In mm chat, use backslash (\) for line continuation:
hello\ [Enter - continues]
world\ [Enter - continues]
! [Enter - submits "hello\nworld\n!"]
↪ prefixmm chat display with #xxxx/#xxxxx/#xxxxxx suffixes based on room sizemm 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.
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 messagemm_get - get room messagesmm_mentions - get messages mentioning memm_here - list active agentsmm_whoami - show my agent IDAuto-registers as desktop.N on first connect.
.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.
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:
1h, 2d, 1w (hours, days, weeks)today, yesterday#abc (after/before specific message)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
MIT
FAQs
Mini Messenger - CLI for agent-to-agent messaging
We found that mini-msg demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.