cc-dm — Claude Code plugin: what it does, how to install
cc-dm is a Claude Code plugin for direct messaging between parallel sessions through a local SQLite message bus, without manual copying between terminals.
MIT ★ 22 updated 2026-03-28
/plugin marketplace add anthropics/claude-plugins-community
/plugin install cc-dm@claude-communityWhat cc-dm does
cc-dm connects multiple Claude Code sessions running side by side on one machine without background daemons or open network ports. Each terminal launches a channel server over stdio, connecting directly to ~/.cc-dm/bus.db configured with SQLite WAL. Running sessions poll this shared database file every 500ms, injecting incoming <channel> events straight into their context windows.
Sessions can exchange targeted direct messages or broadcast notes across all active terminals. Setting CC_DM_SESSION_PROJECT scopes communication strictly to a specific project. Each worker reports heartbeat pings every 30 seconds. Inactive sessions drop off the active roster automatically after 60 seconds of silence.
API key authentication will not work. The Channels protocol strictly requires a claude.ai cloud login, Claude Code version 2.1.80 or newer, and the Bun runtime installed on macOS.
What it helps with
- coordinate parallel agent sessions without copying terminal outputs
- send direct prompts or status updates between planner and worker sessions
- restrict messaging between workers using project scope tags
- inspect active sessions and assigned roles in real time
Example prompts for the agent
- /cc-dm:register
- DM the backend session: auth spec is ready
- Who is active in cc-dm?
How to install cc-dm
Plugin marketplace
/plugin marketplace add anthropics/claude-plugins-community/plugin install cc-dm@claude-communityStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about cc-dm
How do I install cc-dm in Claude Code?
Run /plugin marketplace add anthropics/claude-plugins-community in Claude Code, then execute /plugin install cc-dm@claude-community. Restart Claude Code to load the plugin tools.
What does cc-dm do?
It provides local peer-to-peer messaging between Claude Code terminals on the same machine. Messages travel via an SQLite database file and land in the recipient context within 500ms.
Can I run cc-dm with API key authentication?
No. The Claude Code Channels protocol requires an active claude.ai cloud login. You also need Claude Code v2.1.80 or higher and the Bun runtime.
Source text
SKILL.md · MIT
# cc-dm
[](https://www.npmjs.com/package/cc-dm)
[](https://github.com/Akram012388/cc-dm/blob/main/LICENSE)
Peer-to-peer direct messaging between Claude Code sessions.
## What it does
Running multiple Claude Code sessions in parallel — a planner, a backend worker, a test runner — means context constantly needs to move between terminals. The default workflow is copy-paste: pull text from one session, switch windows, paste into another, lose formatting, lose thread.
cc-dm lets any session DM any other session on the same machine. Messages are delivered as native `<channel>` events within 500ms via the Claude Code Channels protocol, landing directly in the receiving session's context window.
## How it works
```
Session A (planner) ──┐
Session B (backend) ──┼──→ ~/.cc-dm/bus.db (SQLite WAL)
Session C (tests) ──┘ ↑
500ms poll per session
→ <channel> event pushed into context
```
Each session spawns a cc-dm channel server via stdio. The server connects to a shared SQLite database at `~/.cc-dm/bus.db`. When a session sends a message, it writes a row to the bus. Every other session's server polls the bus every 500ms, picks up messages addressed to it, and pushes them as `<channel>` events into its parent session. No daemon, no ports, no network. Just a shared file and a poll loop.
## Requirements
- **Claude Code** v2.1.80 or later
- **claude.ai login** — Channels requires cloud authentication, not API key auth
- **Bun** runtime ([bun.sh](https://bun.sh))
- **macOS** — primary supported platform
## Quick Start
Start a new Claude Code session and enter the following commands:
```
/plugin marketplace add cc-dm-marketplace
/plugin install cc-dm
```
Restart Claude Code. The cc-dm tools and skills will be available in all sessions.
## Install (alternative methods)
**Via npm** (requires [Bun](https://bun.sh)):
```bash
npm install cc-dm
```
The npm package contains the full plugin source. After installing, follow the [Quick Start](#quick-start) above to register the plugin with Claude Code.
> **Note:** cc-dm is a Claude Code channel plugin, not a standalone library. The npm package exists for discoverability and as a distribution mirror — the primary install method is the plugin marketplace above.
**Via curl:**
```bash
curl -fsSL https://raw.githubusercontent.com/Akram012388/cc-dm/main/install.sh | bash
```
## Quick alias
Add this to your `~/.zshrc` or `~/.bashrc`:
```bash
alias cc-dm='claude --dangerously-skip-permissions --dangerously-load-development-channels plugin:cc-dm@cc-dm-marketplace'
```
Then launch sessions with:
```bash
CC_DM_SESSION_NAME=planner CC_DM_SESSION_ROLE=orchestrator CC_DM_SESSION_PROJECT=myapp cc-dm
```
Or just `cc-dm` and register interactively via `/cc-dm:register`.
> **Note:** `--dangerously-skip-permissions` bypasses all tool permission prompts for the session, not just cc-dm's. Use with awareness.
## Usage
Start a session without the alias:
```bash
CC_DM_SESSION_NAME=planner CC_DM_SESSION_ROLE=orchestrator CC_DM_SESSION_PROJECT=myapp \
claude --dangerously-load-development-channels plugin:cc-dm@cc-dm-marketplace
```
Once inside, use natural language:
> "Register this session as planner"
> "DM the backend session: auth spec is ready"
> "Who is active in cc-dm?"
> "Broadcast to all sessions: wrapping up in 10"
## Multi-session orchestration
Open two or more terminals and launch Claude Code with different session identities:
**Terminal 1 — Planner:**
```bash
CC_DM_SESSION_NAME=planner CC_DM_SESSION_ROLE=orchestrator CC_DM_SESSION_PROJECT=myapp claude --dangerously-load-development-channels plugin:cc-dm@cc-dm-marketplace
```
**Terminal 2 — Backend:**
```bash
CC_DM_SESSION_NAME=backend CC_DM_SESSION_ROLE=worker CC_DM_SESSION_PROJECT=myapp claude --dangerously-load-development-channels plugin:cc-dm@cc-dm-marketplace
```
Or skip the env vars and register interactively using `/cc-dm:register` after launch.
Sessions can now message each other directly, broadcast to all, and coordinate work across terminals.
## Session identity
Set these environment variables before launching:
- `CC_DM_SESSION_NAME` — your display name (e.g. `planner`, `backend`, `tests`)
- `CC_DM_SESSION_ROLE` — your role (e.g. `orchestrator`, `worker`, `reviewer`)
- `CC_DM_SESSION_PROJECT` — optional project tag (e.g. `myapp`, `api-server`)
See also: [Message metadata](#message-metadata), [Permission relay](#permission-relay), [Access control](#access-control) for optional env vars that enable advanced features.
If not set, Claude will ask you to register via the `/cc-dm:register` skill on first interaction. Each session gets an auto-generated internal ID (`session-<random hex>`) used for message routing. Sessions send a heartbeat every 30 seconds. A session with no heartbeat for 60 seconds is automatically deleted from the roster. Undelivered messages expire after 15 seconds. No manual cleanup needed.
> **Recommended naming convention:** Use `[project]-[name]` for session names, e.g. `myapp-planner`, `myapp-backend`, `myapp-tests`. Keep the prefix consistent across all workers in the same project and ensure it matches the `CC_DM_SESSION_PROJECT` value. This makes `who` output immediately scannable and helps Claude associate sessions with their project context at a glance.
## Project-scoped messaging
When working across multiple projects or worktrees, both broadcasts and DMs can be scoped to a project. Sessions with a `project` tag can only message other sessions with the same tag. Sessions without a project can message anyone (global, the default).
```bash
# Terminal 1 — frontend worker on myapp
CC_DM_SESSION_NAME=frontend CC_DM_SESSION_ROLE=worker CC_DM_SESSION_PROJECT=myapp cc-dm
# Terminal 2 — backend worker on myapp
CC_DM_SESSION_NAME=backend CC_DM_SESSION_ROLE=worker CC_DM_SESSION_PROJECT=myapp cc-dm
# Terminal 3 — worker on a different project
CC_DM_SESSION_NAME=api-dev CC_DM_SESSION_ROLE=worker CC_DM_SESSION_PROJECT=api-server cc-dm
```
A broadcast from `frontend` reaches `backend` but not `api-dev`. A DM from `frontend` can reach `backend` (same project) but not `api-dev` (different project). A session without a project tag can broadcast and DM any active session — project scoping only restricts outbound messages from sessions that have a tag set.
You can also set the project interactively via `/cc-dm:register` — the skill shows active project tags so you can pick an existing one.
> **Note:** Project scoping is an opinionated default designed for structured multi-project workflows. You can override it at any time — use `/cc-dm:register` or say "register" to change a session's project tag, clear it for global access, or scope it to a different project. This lets you mix isolation styles: keep most workers scoped to their project while leaving a coordinator session global, or temporarily remove a session's project tag when it needs to reach across boundaries.
## Message metadata
The `dm` and `broadcast` tools accept optional metadata fields that are delivered as attributes on the `<channel>` tag:
- **`priority`** — `urgent`, `normal`, or `low`
- **`message_type`** — `task`, `question`, `status`, or `review`
- **`thread_id`** — any string (max 64 chars) to group related messages into a conversation thread
These are purely informational — they don't change delivery behavior. The receiving session's Claude uses them to prioritize, filter, or group messages contextually. If omitted, messages work exactly as before.
> **Example:** `dm(to="backend", content="deploy is broken", priority="urgent", message_type="status")` delivers with `priority="urgent"` and `message_type="status"` visible in the channel event attributes.
## Permission relay
Enables one session to remotely approve or deny tool calls for another session, using the Claude Code Channels `claude/channel/permission` protocol capability. Completely opt-in — off by default.
**Setup:** Add these env vars when launching a worker session that needs remote approval:
```bash
CC_DM_PERMISSION_RELAY=1 \
CC_DM_PERMISSION_APPROVER=orchestrator \
CC_DM_SESSION_NAME=worker CC_DM_SESSION_ROLE=worker CC_DM_SESSION_PROJECT=myapp \
claude --dangerously-load-development-channels plugin:cc-dm@cc-dm-marketplace
```
**How it works:**
1. Worker wants to run a tool (e.g., `Bash rm -rf dist/`)
2. Instead of showing a local approval dialog, cc-dm relays the request to the `orchestrator` session
3. Orchestrator sees: *"Session worker wants to use Bash... Reply with `yes abcde` or `no abcde`"*
4. Orchestrator replies with the verdict — worker's tool call is approved or denied
If `CC_DM_PERMISSION_APPROVER` is not set, the request broadcasts to all project sessions — first response wins. The local terminal approval dialog is always available as a fallback.
| Env var | Required? | Purpose |
|---------|-----------|---------|
| `CC_DM_PERMISSION_RELAY=1` | Yes | Enables the relay; without this, nothing changes |
| `CC_DM_PERMISSION_APPROVER` | No | Name of the session that approves (omit for broadcast) |
## Access control
Optional sender-side restrictions on who can broadcast and who you can DM. All env vars are parsed at session startup — no runtime changes.
```bash
# Only orchestrators and architects can broadcast from this session
CC_DM_BROADCAST_ALLOWED_ROLES=orchestrator,architect
# This session can only DM these specific sessions
CC_DM_DM_ALLOWLIST=planner,reviewer
# OR: this session can DM anyone EXCEPT these (mutually exclusive with allowlist)
CC_DM_DM_BLOCKLIST=intern
```
| Env var | Purpose |
|---------|---------|
| `CC_DM_BROADCAST_ALLOWED_ROLES` | Comma-separated roles allowed to broadcast. Empty = no restriction. |
| `CC_DM_DM_ALLOWLIST` | Comma-separated session names this session can DM. Empty = no restriction. |
| `CC_DM_DM_BLOCKLIST` | Comma-separated session names this session cannot DM. Empty = no restriction. |
`CC_DM_DM_ALLOWLIST` and `CC_DM_DM_BLOCKLIST` are mutually exclusive — setting both causes a fatal error at startup. If neither is set, the session can DM anyone in its project (the default behavior).
> **Note:** Access control is sender-side only. It restricts what THIS session can send, not what it can receive. A session blocked by your allowlist can still DM you.
## Remote access
Claude Code has a built-in `/remote-control` feature that lets you access any session from the Claude iOS app. This pairs naturally with cc-dm — run multiple named sessions locally, drop into any one from your phone, and use cc-dm to coordinate between them.
## Live stream viewer
[cc-dm-stream](https://github.com/Akram012388/cc-dm-stream) is a companion TUI that renders session registrations, messages, broadcasts, and lifecycle events in real time. Run it in a separate terminal to observe the cc-dm bus without joining as a session.
```bash
cc-dm-stream # watch all traffic
cc-dm-stream --project myapp # filter by project
```
Install from within Claude Code using `/cc-dm:install-stream`, or see the [cc-dm-stream repo](https://github.com/Akram012388/cc-dm-stream) for manual install options.
## Bus inspection
Inspect the SQLite bus directly at any time:
```bash
bun -e "
import { Database } from 'bun:sqlite';
const db = new Database(process.env.HOME + '/.cc-dm/bus.db');
console.log(db.query('SELECT * FROM sessions').all());
console.log(db.query('SELECT * FROM messages').all());
"
```
## Releases
| Version | Date | Highlights |
|---------|------|------------|
| [v1.3.1](https://github.com/Akram012388/cc-dm/releases/tag/v1.3.1) | 2026-03-27 | Ghost name theft fix, register skill improvements, lifecycle docs |
| [v1.3.0](https://github.com/Akram012388/cc-dm/releases/tag/v1.3.0) | 2026-03-27 | Message metadata, permission relay, role-based access control |
| [v1.2.0](https://github.com/Akram012388/cc-dm/releases/tag/v1.2.0) | 2026-03-27 | Compaction resilience, heartbeat self-heal |
| [v1.1.0](https://github.com/Akram012388/cc-dm/releases/tag/v1.1.0) | 2026-03-24 | Project-scoped messaging, [npm package](https://www.npmjs.com/package/cc-dm) published |
| [v1.0.0](https://github.com/Akram012388/cc-dm/releases/tag/v1.0.0) | 2026-03-22 | Production release — duplicate delivery guard, same-name protection, stronger session IDs |
| [v0.3.0](https://github.com/Akram012388/cc-dm/releases/tag/v0.3.0) | 2026-03-22 | Fix MCP server path resolution for plugin marketplace installs |
| [v0.2.0](https://github.com/Akram012388/cc-dm/releases/tag/v0.2.0) | 2026-03-21 | 44-test suite, clean shutdown, bus hardening |
| [v0.1.0](https://github.com/Akram012388/cc-dm/releases/tag/v0.1.0) | 2026-03-21 | Initial release |
See [CHANGELOG.md](CHANGELOG.md) for full details.
## Known limitations
**System sleep recovery:** When a laptop sleeps for more than 60 seconds, all cc-dm sessions are marked stale and deleted from the bus by the next cleanup cycle. The heartbeat self-heals automatically — each session re-registers within ~30 seconds of waking. During that window, the session is unreachable via DM or broadcast but the MCP server process continues running. No manual intervention is needed.
## Development status
Built on Claude Code Channels (research preview, v2.1.80+). The `--dangerously-load-development-channels` flag is required until cc-dm is submitted to and approved by the official Channels marketplace. Breaking changes possible as the Channels protocol matures toward GA. Track: https://code.claude.com/docs/en/channels-reference
## Built by
Shaikh Akram Ahmed — architect turned builder, Muscat, Oman.
https://github.com/Akram012388 · https://x.com/CodeAkram
## Privacy
cc-dm operates entirely on your local machine. All data is stored in a local SQLite file (`~/.cc-dm/bus.db`). No data is transmitted over the network, no telemetry is collected, and no external services are contacted.
## License
MIT
© akramdotsh · MIT · akramdotsh/cc-dm