agent-bus is an MCP server that acts as a neutral communication layer enabling local coding agents (Claude Code, Codex, Cursor) to discover each other's sessions, search transcripts, read sessions, ask questions, and hand off context.
list_sessions: List all sessions across agents with liveness status (attached, recent, idle); filter by agent or show only active.
search_sessions: Full-text search all agents' session transcripts, with optional agent filter.
read_session: Read a normalized user/assistant transcript from any session, with message count and character limits.
ask_agent: Ask another agent (Claude Code or Codex) a question headlessly and get its answer synchronously. Supports resuming an existing thread, setting a working directory, overriding models, and write permissions. Includes relay-depth cap (max 2) to prevent loops. Cursor agents cannot be asked.
handoff_session: Transfer session context by generating a markdown brief saved to ~/.agent-bus/handoffs/. Returns a launch command or seeds a new target session and returns its resume command.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agent-bus Ask Codex what it concluded about the flaky auth test."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local communication bus for the coding agents on your machine.
You probably run more than one coding agent — Claude Code in a terminal, Codex in another, Cursor in a window. Each one is an island: it has no idea the others exist, what they're working on, or what they've already figured out. The vendors are quietly building one-way bridges (Codex imports Claude Code transcripts; Claude Desktop has an internal session bus) — but each wants to be the orchestrator, so nobody ships the neutral layer.
agent-bus is that layer: one small MCP server that every agent registers, giving each of them eyes on — and a channel to — all the others. No daemon, no accounts, no cloud. It reads the session stores the agents already write to disk, and relays through the headless CLIs they already ship.
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Claude Code │ │ Codex │ │ Cursor │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ MCP (stdio) │ │
└────────────────────┼────────────────────┘
┌──────┴──────┐
│ agent-bus │
└──────┬──────┘
┌─────────────────┼──────────────────┐
session stores headless CLIs handoff briefs
(~/.claude, …) (claude -p, codex exec) (~/.agent-bus)Tool | What it does |
| Every session across every agent, newest first, with liveness ( |
| Full-text search across all agents' transcripts |
| Normalized user/assistant transcript of any session, from any agent |
| Ask another agent a question, headless and blocking, and get its answer — optionally within an existing thread's context |
| Package a session into a markdown brief and hand it to another agent — either as a ready-to-run command, or by seeding a live target session that acknowledges and waits for you |
So from inside any agent you can say things like:
"What are my other agents working on right now?"
"Ask Codex what it concluded about the flaky auth test."
"Hand this session off to Claude Code and have it pick up where we left off."
Related MCP server: swarm-mcp
It's an MCP server, not a skill and not a service. Each agent speaks MCP natively; registering agent-bus adds its five tools to that agent's toolbox. There is nothing to start and nothing running in the background: MCP stdio servers are spawned by the agent as a child process when a session opens, spoken to over stdin/stdout, and killed when the session ends. Concurrent agents each spawn their own instance — shared state is just the files on disk.
Discovery reads the stores each agent already maintains: Claude Code's ~/.claude/projects/**/*.jsonl, Codex's ~/.codex/sessions rollouts + session_index.jsonl, Cursor's state.vscdb SQLite (read-only, immutable mode).
Asking shells out to the callee's own headless mode — claude -p [--resume <id>], codex exec [resume <id>] — so answers come from a real session of that agent, resumable later, in its own history.
Handoff distills the source transcript into a brief under ~/.agent-bus/handoffs/, then either hands you the launch command or seeds the target session for you and returns its resume command.
Requires Node 18+, macOS (session-store paths are macOS-specific for now), and whichever agents you use on the machine.
One command — detects which hosts are installed, registers the bus with each, merges with any existing MCP config, takes backups before rewriting anything, and is safe to re-run:
npx -y @rjava/agent-bus install # registers with Claude Code, Codex, and Cursor
npx -y @rjava/agent-bus install --dry-run # preview what would change, modify nothingUpgrades are automatic when registered via npx (npx -y resolves the latest published version each spawn); re-run install only if registration instructions change.
claude mcp add --scope user agent-bus -- npx -y @rjava/agent-bus
codex mcp add agent-bus -- npx -y @rjava/agent-bus
# Cursor: add to ~/.cursor/mcp.json → { "mcpServers": { "agent-bus": { "command": "npx", "args": ["-y", "@rjava/agent-bus"] } } }From a clone (for development): git clone https://github.com/rishabhjava/agent-bus && cd agent-bus && npm install, then node cli.mjs install — it registers the clone's path instead of npx.
Codex note: Codex prompts for approval on an MCP server's first tool call ("always allow" persists it). Headless
codex execcannot answer that prompt — to use the bus headlessly, setdefault_tools_approval_mode = "auto"under[mcp_servers.agent-bus]in~/.codex/config.toml.
New sessions of each agent pick the tools up automatically. Smoke-test without any agent:
npm run smoke # list tools, list sessions, read one per agent
node test/smoke.mjs ask claude # cheap round-trip through claude -pLetting agents talk to each other is letting untrusted inputs talk to each other, so the bus is deliberately paranoid:
Provenance headers — every relayed prompt is prefixed with a notice that it comes from a peer agent, not the human, and should be treated as untrusted input.
Loop guard — a relay-depth counter propagates through the child process tree (AGENT_BUS_DEPTH) and hard-refuses at depth 2, so two agents can never recursively prompt each other into a token bonfire.
No permission laundering — the bus never widens the callee's permissions: Codex calls run sandboxed read-only unless explicitly allowed to write, and Claude calls run headless under its default permission mode.
Prototype, built and verified on one machine in one sitting. Parsers for the vendors' session formats are defensive but the formats are undocumented and will drift.
ask_agent waits timeout_s seconds for the callee (default 240; minimum 30; 0 means no bus-side timeout — wait until the callee exits). Two caveats the bus cannot lift: the host running the tool call may cancel long MCP calls on its own clock (Claude Code honors MCP_TOOL_TIMEOUT; Codex has per-server tool_timeout_sec in ~/.codex/config.toml), and if the bus process dies mid-ask it kills its delegated child processes rather than orphan them — the answer is lost either way. For work longer than a few minutes, handoff_session is the durable path.
Cursor is read-only (discovery + handoff source) until its headless CLI is present.
Asking a thread that is currently open interactively does not inject into the live TTY — the callee answers out-of-band, from a snapshot of that thread's context. With Claude Code, the exchange isn't even a separate session: it lands in the same session file as a parallel branch (same session id, different parent chain), which the live view never displays. Observed in practice when a Codex session used ask_agent on the live Claude Code session that was building this project — the answer was correct, and the live session only learned about the exchange by reading its own transcript off disk. True live injection needs harness cooperation; that's the interesting next problem.
MIT
Ask another local agent a question and get its answer (headless, blocking). Pass session_id to ask within an existing thread's context — the answer comes from a snapshot of that thread (for Claude Code, a hidden parallel branch in the same session); a live interactive view of it will not see the exchange. Codex runs sandboxed read-only unless allow_writes. Cursor is not askable (no CLI). Relay depth is capped at 2 to prevent agent-to-agent loops.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory for the callee | |
| from | No | Who is asking, e.g. 'claude session abc123' | |
| agent | Yes | ||
| model | No | claude only: model override, e.g. 'haiku' | |
| prompt | Yes | ||
| timeout_s | No | Default 240 | |
| session_id | No | Existing thread to resume for context | |
| allow_writes | No | codex only: workspace-write sandbox |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It transparently discloses headless/blocking behavior, session_id side effects (hidden parallel branch), codex sandbox restrictions, and relay depth limit. This is comprehensive for a complex tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph of five sentences, all front-loaded with the core action. Every sentence adds critical context (headless, blocking, session mechanics, sandbox, relay limit, unaskable agents). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, 2 required, and multiple behavioral nuances, the description covers the key points: headless/blocking, session context, sandboxing, relay limit, and which agents are askable. It does not explicitly describe return value format or error handling, but the tool is blocking and returns an answer directly. Minor gap but overall solid.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, high enough that description need not cover every param. The description adds value beyond schema by explaining session_id's effect (thread snapshot, hidden exchange) and allow_writes (sandbox override for codex). This enriches parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Ask another local agent a question and get its answer (headless, blocking).' It specifies the verb (ask) and resource (another local agent). The sibling tools all relate to session management, so this tool's purpose is distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for usage: passing session_id for thread context, relay depth cap, and cursor being unaskable. It doesn't explicitly state when to use versus alternatives, but the sibling tools are sufficiently different that no comparison is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hand a session's context from one agent to another. Builds a markdown brief from the source transcript, saves it under ~/.agent-bus/handoffs/, and either returns a ready-to-run launch command (launch=false) or seeds a new target session and returns its resume command (launch=true).
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Override working directory | |
| tail | No | Messages to include (default 25) | |
| launch | No | Actually seed the target session now | |
| to_agent | Yes | ||
| from_agent | Yes | ||
| session_id | Yes | ||
| instructions | No | What the target agent should do next |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers key behaviors: building a markdown brief, saving to ~/.agent-bus/handoffs/, and conditional seeding. It does not detail side effects (e.g., file persistence) or authorization needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose, second explains mechanics. Front-loaded with the verb and resource, no filler. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, 7 parameters, moderate complexity. The description covers the workflow but does not describe return values (e.g., format of commands) or what happens on failure. Adequate but incomplete for full agent guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 57%. The description adds context only for the launch parameter (false returns command, true seeds session). Other parameters like from_agent, to_agent, session_id, instructions are not elaborated, leaving the agent to infer meaning from schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Hand a session's context from one agent to another.' It specifies the actions (builds a markdown brief, saves it, returns command) and distinguishes from siblings like read_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the two modes via the launch parameter (return command vs. seed session). It implies when to use this tool (for handoffs), but lacks explicit instructions on when not to use it or alternatives like read_session.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List coding-agent sessions on this machine across Claude Code, Codex, and Cursor. live: 'attached' (a running process references this session), 'recent' (updated <5 min ago), or 'idle'.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | No | Filter to one agent | |
| limit | No | Max results (default 30) | |
| live_only | No | Only sessions that look active |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explains the meaning of live statuses (attached, recent, idle) and implies a read-only nature. However, it does not detail return format or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no fluff. It is front-loaded with the core purpose and then explains the live statuses. Every sentence is essential.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description omits what fields sessions contain. It covers the listing scope and live statuses but leaves the return structure unspecified, which is a gap for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context for live_only by defining statuses, but for agent and limit it only restates schema info. Minimal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists coding-agent sessions across specific agents (Claude Code, Codex, Cursor) and explains the live statuses, distinguishing it from sibling tools like search_sessions or read_session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives like search_sessions or handoff_session. It lacks explicit when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a normalized transcript (user/assistant messages) of any agent's session.
| Name | Required | Description | Default |
|---|---|---|---|
| tail | No | Last N messages (default 20) | |
| agent | Yes | ||
| max_chars | No | Truncate each message (default 2000) | |
| session_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It does not mention error handling, authorization, or return format, leaving significant gaps for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single, efficient sentence (9 words) that conveys the core purpose without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 4 parameters and no output schema, the description provides no behavioral context, error details, or return-value information, making it incomplete for an agent's decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 50% of parameters (tail and max_chars). The tool description adds no additional parameter semantics, failing to compensate for the undocumented agent and session_id parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool reads a normalized transcript of any agent's session, distinguishing it from sibling tools like list_sessions (listing) and search_sessions (searching).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., list_sessions, search_sessions). The description only states what it does, not when to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search across all agents' session transcripts. Returns matching session ids.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | No | ||
| limit | No | ||
| query | Yes | Literal text to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for revealing behavioral traits. It states it performs a full-text search and returns IDs, but does not disclose read-only nature, performance implications, authentication requirements, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (two sentences) and front-loaded with the key action. No unnecessary words, though additional details could be added without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema and annotations, the description is insufficiently complete. It does not cover search scope details (e.g., case sensitivity), the role of the 'agent' filter, or what 'full-text' includes. The return type is stated, but more context is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (33%) meaning only the 'query' parameter has a description. The tool description adds no additional parameter information beyond what is in the schema; it does not explain the 'agent' enum or 'limit' constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a full-text search across all agents' session transcripts and specifies that it returns matching session IDs. This distinguishes it from siblings like list_sessions and read_session, though it could more explicitly differentiate from ask_agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention typical use cases, prerequisites, or situations where other tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0ask_agenthandoff_sessionlist_sessionsread_sessionsearch_sessionsEach tool has a clearly distinct purpose: listing sessions, searching transcripts, reading transcripts, asking agents, and handing off sessions. No ambiguity.
All tools follow a consistent verb_noun pattern with snake_case (list_sessions, search_sessions, read_session, ask_agent, handoff_session), making them predictable.
With 5 tools, the server is well-scoped for its domain of managing agent sessions and interactions, avoiding bloat or insufficiency.
The tool set covers all key operations for inter-agent communication and session management: discovery (list, search), reading, querying, and handoff. No obvious gaps for the stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
shared AI-context layer for teams — persistent memory your agents search and update over MCP
Shared memory and actions for Claude, Kiro, OpenAI, Cursor, and other MCP-compatible AI clients.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/rishabhjava/agent-bus'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
