{"id":50556923,"url":"https://github.com/yaniv-golan/cc-mess","last_synced_at":"2026-06-04T08:01:13.155Z","repository":{"id":346589281,"uuid":"1189060125","full_name":"yaniv-golan/cc-mess","owner":"yaniv-golan","description":"Inter-Claude-Code communication plugin — mesh networking for multiple Claude Code instances","archived":false,"fork":false,"pushed_at":"2026-04-04T16:11:05.000Z","size":4332,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-04T19:14:47.826Z","etag":null,"topics":["agent-communication","ai-agents","claude-code","claude-code-channels","claude-code-plugin","cli","mcp","mcp-server","mesh-networking","model-context-protocol","multi-agent","orchestration","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yaniv-golan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T23:46:01.000Z","updated_at":"2026-04-04T16:11:08.000Z","dependencies_parsed_at":"2026-03-25T18:04:20.131Z","dependency_job_id":null,"html_url":"https://github.com/yaniv-golan/cc-mess","commit_stats":null,"previous_names":["yaniv-golan/cc-mess"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/yaniv-golan/cc-mess","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaniv-golan%2Fcc-mess","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaniv-golan%2Fcc-mess/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaniv-golan%2Fcc-mess/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaniv-golan%2Fcc-mess/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yaniv-golan","download_url":"https://codeload.github.com/yaniv-golan/cc-mess/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yaniv-golan%2Fcc-mess/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33895175,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-communication","ai-agents","claude-code","claude-code-channels","claude-code-plugin","cli","mcp","mcp-server","mesh-networking","model-context-protocol","multi-agent","orchestration","typescript"],"created_at":"2026-06-04T08:01:11.679Z","updated_at":"2026-06-04T08:01:13.134Z","avatar_url":"https://github.com/yaniv-golan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/banner.png\" alt=\"cc-mess — mesh networking for Claude Code\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# cc-mess\n\nInter-Claude-Code communication plugin — mesh networking for multiple Claude Code instances. Enables discovery, communication, task delegation, and emergent trust relationships using a file-based transport layer and symmetric peer architecture.\n\n\u003e **Note:** cc-mess uses Claude Code's [Channels](https://code.claude.com/docs/en/channels-reference) feature (research preview) for real-time message delivery between instances. Channels are experimental and require the `--dangerously-load-development-channels` flag. The API and behavior may change in future Claude Code releases.\n\n## Architecture\n\n```mermaid\ngraph TD\n    Human[Human via Telegram] \u003c--\u003e|cc-telegram-plus| Coordinator\n    Coordinator[Coordinator Instance\u003cbr/\u003eapollo-3f2a] \u003c--\u003e|file-based inbox| WorkerA[Worker\u003cbr/\u003ehermes-c1b7]\n    Coordinator \u003c--\u003e|file-based inbox| WorkerB[Worker\u003cbr/\u003eathena-9d4e]\n    WorkerA \u003c--\u003e|peer-to-peer| WorkerB\n\n    subgraph \"~/.claude/channels/mess/\"\n        Registry[registry.json]\n        Control[control.json]\n        Config[config.json]\n        Inboxes[inboxes/]\n    end\n\n    Coordinator --- Registry\n    WorkerA --- Inboxes\n    WorkerB --- Inboxes\n```\n\n## Setup\n\n### 1. Build cc-mess\n\n```bash\ncd /path/to/cc-mess\nnpm install\nnpm run build\n```\n\n### 2. Add to your project\n\nIn your project directory, create `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"cc-mess\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/cc-mess/dist/server.js\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n### 3. Configure the mesh\n\nCreate `~/.claude/channels/mess/config.json`:\n\n```json\n{\n  \"allowed_directories\": [\"/path/to/your/projects/*\"],\n  \"max_instances\": 10,\n  \"max_spawn_depth\": 3,\n  \"require_telegram_relay\": false,\n  \"default_guardrail\": \"permissive\"\n}\n```\n\nSet `require_telegram_relay: true` if you want to enforce Telegram visibility before workers can be spawned.\n\n### 4. Pre-allow MCP tools\n\nIn your project's `.claude/settings.json`:\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"mcp__cc-mess__list_instances\",\n      \"mcp__cc-mess__send\",\n      \"mcp__cc-mess__broadcast\",\n      \"mcp__cc-mess__reply\",\n      \"mcp__cc-mess__spawn\",\n      \"mcp__cc-mess__kill\",\n      \"mcp__cc-mess__update_self\",\n      \"mcp__cc-mess__mesh_control\",\n      \"mcp__cc-mess__send_as_human\"\n    ]\n  }\n}\n```\n\n## Running\n\n### Start the coordinator\n\nThe `--dangerously-load-development-channels server:cc-mess` flag is required for instances to receive messages from each other. Without it, MCP tools work but channel notifications (inbound messages) are silently dropped.\n\n```bash\nCC_MESS_ROLE=coordinator claude --dangerously-load-development-channels server:cc-mess\n```\n\n### Start a worker (interactive)\n\nIn another terminal, from the same project directory:\n\n```bash\nCC_MESS_ROLE=worker claude --dangerously-load-development-channels server:cc-mess\n```\n\n### Start a worker (one-shot task)\n\n```bash\nCC_MESS_ROLE=worker claude --dangerously-load-development-channels server:cc-mess \\\n  \"You are a mesh worker. Call list_instances to see the mesh, then do your assigned task.\"\n```\n\n### Tmux dashboard\n\nLaunch a full dashboard with coordinator, viewer, and auto-created worker panes:\n\n```bash\nnpm run dashboard -- --no-telegram --clean\n```\n\n- `--no-telegram` — disable the Telegram relay requirement for spawning\n- `--clean` — wipe previous mesh state (registry, inboxes, audit) and start fresh\n\nWorkers spawned from the coordinator automatically appear as interactive panes in the dashboard.\n\n### Conversation viewer\n\nView the message timeline between instances:\n\n```bash\nnpm run viewer                    # show all messages\nnpm run viewer -- --follow        # live-tail new messages\nnpm run viewer -- --last 20       # show last 20 messages\nnpm run viewer -- --from hermes   # filter by sender\n```\n\n### Spawn a worker from the coordinator\n\nInside the coordinator session:\n\n```\nspawn(cwd: \"/path/to/project\", task: \"Refactor the auth module\")\n```\n\nThis launches a new Claude Code process with the cc-mess plugin injected automatically.\n\n## MCP Tools\n\n| Tool | Purpose |\n|------|---------|\n| `send` | Send a message to a specific instance by name |\n| `broadcast` | Send a message to all instances (or filtered subset) |\n| `reply` | Reply to a received message (threads via `in_reply_to`) |\n| `list_instances` | Show the current registry — who's alive, what they're doing |\n| `spawn` | Launch a new Claude Code instance with a task |\n| `kill` | Ask an instance to gracefully shut down |\n| `update_self` | Update own registry entry (task, capabilities) |\n| `mesh_control` | Pause, resume, or shut down the entire mesh (coordinator only) |\n| `send_as_human` | Route a Telegram message to an instance as the human (coordinator only) |\n\n## Telegram Integration\n\nThe coordinator can relay mesh events to Telegram via [cc-telegram-plus](https://github.com/yaniv-golan/cc-telegram-plus). See [`docs/coordinator-claude-md.md`](docs/coordinator-claude-md.md) for the CLAUDE.md template that enables:\n\n- Auto-relay of spawns, exits, crashes, task delegation, and results\n- Human-to-instance messaging via `@name` prefix\n- `/mess` commands (status, kill, spawn, pause, resume, shutdown_all, logs, verbosity)\n\n### Relay config\n\nCreate `~/.claude/channels/mess/relay.json`:\n\n```json\n{\n  \"chat_id\": \"your-telegram-chat-id\",\n  \"verbosity\": \"normal\"\n}\n```\n\nVerbosity levels: `quiet` (errors only), `normal` (spawns, exits, tasks), `verbose` (everything including chat).\n\n## Configuration Reference\n\n| Key | Type | Default | Description |\n|-----|------|---------|-------------|\n| `allowed_directories` | `string[]` | `[]` | Glob patterns for valid spawn locations |\n| `max_instances` | `number` | `10` | Hard cap on total mesh size |\n| `max_spawn_depth` | `number` | `3` | Maximum spawn chain depth |\n| `require_telegram_relay` | `boolean` | `true` | Require active Telegram relay for spawning |\n| `default_guardrail` | `string` | `\"permissive\"` | Default guardrail profile for spawned instances |\n\n## Guardrail Profiles\n\n- **`strict`** — Read-only. Allows `Read`/`Glob`/`Grep` within cwd, limited Bash commands, blocks writes/web access. For review tasks and code analysis.\n- **`permissive`** — Full development sandbox. Allows read/write within cwd, Bash (except `git push`), package registry access. For implementation tasks.\n- **`custom`** — Inline tool-level policies specified at spawn time via `custom_policies`.\n\n## Transport\n\nAll state lives under `~/.claude/channels/mess/`. File-based message queues with atomic writes (temp + rename), lockfile-protected registry, and at-least-once delivery with persistent deduplication.\n\n## Development\n\n```bash\nnpm install\nnpm run build      # Compile TypeScript\nnpm run dev        # Watch mode\nnpm run test       # Run tests (114 tests)\nnpm run lint       # Lint\nnpm run typecheck  # Type check\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyaniv-golan%2Fcc-mess","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyaniv-golan%2Fcc-mess","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyaniv-golan%2Fcc-mess/lists"}