{
  "markdown": "# Agent Synapse\n\n[![npm version](https://img.shields.io/npm/v/agent-synapse)](https://www.npmjs.com/package/agent-synapse)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n![Agent Synapse](assets/banner.svg)\n\nCross-project messaging between Claude Code sessions via named agents.\n\nAgent Synapse lets multiple Claude Code sessions talk to each other — even across different project folders. Each session gets a codename. Agents send messages to each other by name, check their inbox, and see who's online.\n\n```\nTerminal 1 (~/backend)              Terminal 2 (~/frontend)\n┌──────────────────┐                ┌──────────────────┐\n│ Agent: \"backend\"  │   send_message │ Agent: \"frontend\" │\n│                   │ ──────────────>│                   │\n│ Claude Code       │    (broker)    │ Claude Code       │\n└──────────────────┘                └──────────────────┘\n         │                                   │\n         └──────── Synapse Broker ───────────┘\n              (localhost:3117, auto-started)\n```\n\n## What can I build with this?\n\n- **Cross-project handoffs** — a frontend agent asks its orchestrator for API details; the orchestrator messages the backend orchestrator, who routes to the right agent and sends back the answer\n- **Specialist teams** — a builder agent implements, a fixer agent patches bugs, an orchestrator coordinates — each with its own focused context\n- **Any multi-step workflow** — set up agents with specific roles and pass context from one to the next, no copying and pasting between terminals\n\n## Requirements\n\n- Node.js >= 18\n- Claude Code (with a claude.ai account — API key auth is not supported)\n\n## Quickstart\n\n```bash\n# Install\nnpm install -g agent-synapse\n\n# One-time setup (registers MCP server, installs hook, configures status line)\nagent-synapse setup\n```\n\nThen open two terminals:\n\n```bash\n# Terminal 1\nSYNAPSE_AGENT_NAME=backend claude\n\n# Terminal 2\nSYNAPSE_AGENT_NAME=frontend claude\n```\n\nThe broker starts automatically when the first agent connects.\n\nIn Terminal 1, say: *\"Send frontend a message: the API is ready at POST /api/meetings\"*\n\nTerminal 2 will pick it up after the next tool use.\n\n### Real-time push (optional)\n\nStandard mode works great on its own — messages are checked after every tool use. If you want instant delivery without any delay, add the channels flag:\n\n```bash\nSYNAPSE_AGENT_NAME=backend claude --dangerously-load-development-channels server:synapse\n```\n\nThis enables Claude Code's Channels API for real-time push. The flag sounds alarming but everything runs locally — it just bypasses Anthropic's allowlist while Synapse is in development. It will go away once Synapse is published as an approved plugin.\n\n## Creating Agents\n\nFor reusable, long-lived agents you can create a persistent agent with its own `CLAUDE.md`. This lets you open the agent by simply running `claude` from its folder — no env var needed.\n\n### From inside a Claude session\n\nIf you're already in Claude and want to create a new agent on the fly:\n\n> *\"Create an agent called data-pipeline that handles ETL jobs and knows about our Postgres schema\"*\n\nThis calls the `create_agent` tool, which creates `agents/data-pipeline/CLAUDE.md` in your current project and prints the command to open it.\n\n### From the terminal\n\n```bash\n# In your project directory\nagent-synapse create-agent data-pipeline \"Handles ETL jobs and knows about our Postgres schema\"\n```\n\nBoth approaches create:\n\n```\nyour-project/\n└── agents/\n    └── data-pipeline/\n        └── CLAUDE.md      ← identity + Synapse self-registration instruction\n```\n\nThe agent registers itself automatically when the session starts — no extra steps.\n\nTo start the agent:\n\n```bash\ncd agents/data-pipeline && claude\n```\n\n## Agent Naming\n\nThree ways to set the agent name, in order of precedence:\n\n**1. Environment variable** — most explicit, set before launching Claude:\n```bash\nSYNAPSE_AGENT_NAME=backend claude\n```\n\n**2. Self-registration via CLAUDE.md** — for created agents, the `CLAUDE.md` instructs the agent to register itself at session start. The status line updates once registration completes.\n\n**3. Folder name fallback** — if neither of the above is set, defaults to the current folder name (e.g. `~/projects/backend` becomes `backend`).\n\n## Tools\n\nOnce connected, Claude has these tools:\n\n| Tool | Description |\n|------|-------------|\n| `send_message` | Send a message to another agent by name |\n| `check_messages` | Check your inbox for messages from other agents |\n| `list_agents` | See all registered agents and their status |\n| `register_agent` | Set or change the agent name for this session |\n| `rename_agent` | Rename this session's agent, migrating its identity and any pending messages |\n| `unregister_agent` | Remove this session's registration so it stops receiving messages |\n| `create_agent` | Create a new agent with a `CLAUDE.md` in the current project |\n\n## CLI\n\n```bash\nagent-synapse setup                            # Configure Synapse (run once)\nagent-synapse create-agent <name> [desc]       # Create a new agent in ./agents/<name>/\nagent-synapse broker start                     # Start broker manually (usually auto-started)\nagent-synapse broker stop                      # Stop the broker\nagent-synapse broker status                    # Show broker and connected agents\nagent-synapse uninstall                        # Remove Synapse from Claude Code settings\nagent-synapse version                          # Show version\n```\n\n## How It Works\n\nSynapse supports two delivery modes:\n\n**Standard mode** (no flag needed):\n1. Agent A sends a message to Agent B via the `send_message` tool\n2. The broker queues the message\n3. After Agent B's next tool use, a PostToolUse hook checks for pending messages\n4. Claude sees the notification and calls `check_messages` to retrieve them\n\n**Channel mode** (with `--dangerously-load-development-channels`):\n1. Agent A sends a message to Agent B via the `send_message` tool\n2. The broker pushes it instantly via SSE\n3. The message appears in Agent B's context as a `<channel>` tag — no polling needed\n\nIn both modes, if the target agent is offline, messages are queued to disk and delivered on reconnect.\n\n## What `setup` does\n\nRunning `agent-synapse setup` configures three things:\n\n1. **MCP server** — Registers Synapse globally in `~/.claude.json` so the tools are available in every Claude Code session\n2. **Hooks** — Adds PostToolUse and UserPromptSubmit hooks to `~/.claude/settings.json` that check for pending messages and nudge Claude to read them\n3. **Status line** — Wraps your existing status line to show the agent name and pending message count (e.g. `backend [synapse: backend (3)]`)\n\n## Architecture\n\n**Broker** — Lightweight HTTP server on `localhost:3117`\n- Routes messages between agents via SSE (channel mode) or queue polling (standard mode)\n- Persists undelivered messages to disk (`~/.claude-synapse/queues.jsonl`)\n- Zero external dependencies (Node.js stdlib only)\n\n**MCP Server** — Registered globally, spawned per Claude Code session\n- Provides `send_message`, `check_messages`, `list_agents`, `register_agent`, `rename_agent`, `unregister_agent`, and `create_agent` tools\n- Auto-starts the broker if it's not running\n- Writes a session file (`~/.claude-synapse/session-<ppid>.name`) when an agent registers so the status line can show the name even without `SYNAPSE_AGENT_NAME` being set\n\n## Security\n\n- Broker binds to `127.0.0.1` only — not exposed to your network\n- All requests require an auth token generated during setup\n- Data directory and file permissions are locked down (`700` / `600`)\n- Max message size: 100KB, max queue depth: 100 messages per agent\n\n**One thing to keep in mind:** messages from other agents enter Claude's context. Don't pass secrets or credentials through Synapse — treat agent messages like any other external input.\n\n## License\n\nMIT\n",
  "bytes": 7887,
  "sha": "7aa975b6cdad4bdfd68dd7d1dabb1bac12606daea74b9d3f7591b441c068cf94",
  "repo_slug": "disposablebydefault/agent-synapse",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_disposablebydefault_agent_synapse_agent__8e3c6144/readme"
}