claude-intercom
Enables cross-session communication between Claude Code sessions, allowing them to discover, message, and interact with each other through async messaging and synchronous question-answering.
list_sessions— Discover recent or currently live Claude Code sessions, optionally filtered by scope (recent,live,all) or project name.whoami— Identify your own session ID, project, and working directory so other sessions can address you.send_message— Send an async message to another session's inbox; optionally push it live into their tmux terminal.read_messages— Read your inbox of cross-session messages, with an option to show only unread ones.reply— Reply to a specific received message by ID, delivering your response to the original sender's inbox (and optionally their live terminal).ask— Inject a question directly into a live session's terminal and wait for its synchronous answer, read back from its transcript (configurable timeout). Can also resume idle sessions headlessly.Hands-off pickup — An optional Stop hook automatically reads and processes incoming messages without manual
read_messagescalls.
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., "@claude-intercomAsk the data-pipeline session if the ETL job finished."
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.
claude-intercom
An MCP server that lets Claude Code sessions talk to each other.
Run many Claude Code sessions at once (e.g. with agent-deck, tmux, or just several terminals) and let them:
list_sessions— discover recent sessions and see which are live right nowwhoami— find out which session you aresend_message— drop an async message into another session's inboxread_messages— pick up messages other sessions sent youreply— answer a message you receivedask— ask a live session a question and get its answer back synchronously
No daemon, no database. Messages are plain JSON files under ~/.claude-intercom/, and sessions are discovered from Claude Code's own transcripts (~/.claude/projects/).
How it works
Discovery. Every Claude Code session writes a transcript to
~/.claude/projects/<project>/<session-id>.jsonl.list_sessionsreads those for the session id, project, first prompt (as a title), and last-active time.Liveness. A session is "live" if its
claudeprocess is running inside a tmux pane. The server correlates tmux panes → processes → the session id each one has open.Self-identity. The server walks up from its own process to the parent
claudeprocess and useslsofto find which transcript that process has open — that's you. (Override withCLAUDE_INTERCOM_SESSIONif detection ever fails.)Live delivery /
ask. For a live target, the message is typed into its tmux pane withtmux send-keys. Forask, the server then tails the target's transcript and returns the assistant text that appears in response.
Heads up: live delivery and
askinterrupt whatever the target session is doing, exactly as if you typed into its terminal. Asyncsend_message(the default) does not — the recipient sees it when it next callsread_messages.
Related MCP server: claude-session-bridge
Requirements
Node.js ≥ 18
tmux,ps, andlsofonPATH(standard on macOS/Linux) — only needed for liveness, live delivery, andask. Async messaging works without them.
Install
From source (recommended today)
git clone https://github.com/AriOliv/claude-intercom
cd claude-intercom
npm install
npm run buildThen register it with Claude Code (user scope = available in every session):
claude mcp add intercom -s user -- node "$(pwd)/dist/index.js"If you run several Claude Code config dirs, register it in each:
CLAUDE_CONFIG_DIR=~/.claude claude mcp add intercom -s user -- node "$(pwd)/dist/index.js"
CLAUDE_CONFIG_DIR=~/.claude-ari claude mcp add intercom -s user -- node "$(pwd)/dist/index.js"Via npx (once published to npm)
claude mcp add intercom -s user -- npx -y claude-intercomOr add it to your MCP config manually:
{
"mcpServers": {
"intercom": {
"command": "node",
"args": ["/absolute/path/to/claude-intercom/dist/index.js"]
}
}
}Usage
In any Claude Code session:
"List the other sessions I have open."
"Ask the litellm session whether the model-selection refactor is merged yet."
"Tell the BRLA session I'm done with the migration — it can rebase."
"Check my intercom inbox."
Configuration
Env var | Default | Purpose |
|
| Where Claude Code stores |
|
| Where messages are stored |
| (auto) | Force this server's session identity (a session id) |
| (empty) | Extra flags passed to |
Reaching idle sessions
ask works whether the target is live or idle. A live session (running in a
tmux pane) gets the question typed into its terminal. An idle session — one
whose transcript exists but isn't currently running — is resumed headlessly with
claude -p --resume <id> in its own cwd, so you can still reach it; the thread
continues in the same transcript. Set CLAUDE_INTERCOM_RESUME_FLAGS if those
headless resumes need extra flags.
Hands-off pickup (optional Stop hook)
hooks/pickup-stop.mjs is a Claude Code Stop hook: when a session finishes a
turn, it pulls any unread messages addressed to that session and feeds them back
so the session handles them (and replies) without anyone calling read_messages.
Register it in settings.json:
{ "hooks": { "Stop": [ { "hooks": [
{ "type": "command", "command": "node /absolute/path/to/claude-intercom/hooks/pickup-stop.mjs" }
] } ] } }Development
npm install
npm run build # compile to dist/
npm run dev # run from source with tsxLimitations
Liveness, live delivery, and
askassume sessions run inside tmux. Plain-terminal sessions still work forlist_sessionsand asyncsend_message/read_messages.askreads the answer by tailing the target's transcript; it returns the assistant text produced after the question, capped at ~4k chars. It's pragmatic, not a structured RPC.A session only checks its inbox when something calls
read_messages(or you tell it to). Pair it with a hook or a polling loop if you want hands-off pickup.
License
MIT
Available Tools
6 toolsaskA
Ask a LIVE session a question and wait for its answer. Injects the question into the target's running terminal, then reads the answer back from its transcript. Only works on sessions marked live in list_sessions. Note: this interrupts what the target is currently doing.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | target session id or prefix (must be live) | |
| question | Yes | the question to ask | |
| wait_seconds | No | how long to wait for an answer (default 90) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses injection into running terminal and reading from transcript. No annotations provided, so description carries full burden; side effect of interruption is noted.
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?
Three sentences cover purpose, mechanism, and constraint without redundancy. Front-loaded with primary action.
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?
Adequately describes behavior and prerequisites but lacks explicit return value format or error handling (e.g., timeout, non-live session). No output schema to compensate.
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 already covers 100% of parameters with descriptions. Description adds no new semantic details beyond the mechanism of injection/reading.
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?
Clearly states the tool asks a LIVE session a question, injects into terminal, reads answer. Distinct from siblings like list_sessions (listing) and send_message (sending messages).
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?
Explicitly states only works on live sessions (from list_sessions) and warns about interrupting the target. Lacks explicit alternatives for non-live sessions but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_sessionsA
List Claude Code sessions discovered on this machine — recent ones and which are currently live (running in a tmux pane). Use scope='live' to see only sessions you can reach right now, or pass a project filter.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | recent = sorted by last activity (default), live = only running sessions, all = everything | |
| project | No | filter by project name or path substring | |
| limit | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions sessions are discovered on the machine and live ones are in tmux panes, implying a read-only operation. However, it does not disclose potential side effects, authentication requirements, or rate limits. The description is adequate but not thorough.
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 long. The first sentence states the purpose clearly, and the second provides usage guidance. Every sentence is meaningful and there is no redundancy or 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?
The tool has 3 parameters with no output schema. The description explains the purpose and basic usage of scope and project, but does not mention the limit parameter or what the output format contains. For a simple list tool, it provides core context but lacks details about output and all parameters.
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?
The input schema covers 67% of parameters with descriptions (scope and project), but limit lacks description. The description adds context beyond the schema: explaining how to use scope='live' and project filter. It does not mention the limit parameter. Overall, it adds value but does not fully compensate for missing schema coverage.
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 lists Claude Code sessions, distinguishing between recent and live ones. It is specific about the resource (sessions) and action (list), and the sibling tools are all different types (chat-related), so no confusion.
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 usage guidance: 'Use scope='live' to see only sessions you can reach right now, or pass a project filter.' This tells when to use specific parameters. However, it does not explicitly state when not to use the tool or mention alternatives among siblings, which are unrelated anyway.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_messagesA
Read intercom messages other sessions have sent to you. Call this at the start of a turn (or when prompted) to pick up cross-session messages. Marks them read.
| Name | Required | Description | Default |
|---|---|---|---|
| unread_only | No | only return messages you haven't read yet (default true) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the tool marks messages as read, which is a side effect. However, with no annotations, the description could mention more about idempotency or authentication requirements.
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?
Three concise sentences, front-loaded with purpose. 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?
For a simple tool with one parameter and no output schema, the description adequately explains purpose, usage, and side effect. Lacks explicit mention of return format but is still complete enough.
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% for the only parameter. The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.
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?
Clearly states the tool reads intercom messages from other sessions, which is a specific verb and resource. Distinguished from sibling tools like send_message or reply.
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?
Explicitly advises to call at start of turn or when prompted to pick up cross-session messages, providing clear context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
replyA
Reply to a message in your inbox. Looks up the original sender by message id and delivers your reply to their inbox (and live, if they're running).
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | the message id (or prefix) you are replying to, from read_messages | |
| text | Yes | your reply | |
| deliver_live | No | also push the reply into the sender's terminal if it is live (default true) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of disclosing behavioral traits. It effectively reveals key behaviors: it looks up the original sender by message ID, delivers the reply to their inbox, and optionally pushes it live. This goes beyond the input schema by explaining the internal process. However, it does not mention potential side effects (e.g., what happens if message ID is invalid) or permissions needed.
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 concise, consisting of two straightforward sentences. It front-loads the core purpose ('Reply to a message in your inbox') and then provides the key mechanic. Every word earns its place; there is no fluff or redundancy.
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 tool has 3 parameters, no output schema, and no annotations, the description is somewhat complete but lacks details. It explains the main action and one optional behavior (live delivery), but does not describe the response format, error cases, or prerequisites (e.g., must have read messages to get a message ID). For a mutation tool, knowing the return value or acknowledgment would be useful.
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?
All three parameters have schema descriptions with 100% coverage, so the baseline is 3. The description adds some context—explaining that the reply is delivered to the original sender's inbox and can be live—but does not substantially enrich the parameter meanings beyond what the schema already provides. For example, the schema already describes 'deliver_live' as pushing to terminal if live.
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: 'Reply to a message in your inbox.' It specifies the action (reply), the resource (message in inbox), and how it works (looks up original sender, delivers reply to their inbox and optionally live). This distinguishes it from siblings like 'send_message' (which sends a new message) and 'ask' (which might ask a question).
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 implies when to use this tool—when you need to reply to an existing message in your inbox. However, it does not explicitly tell when not to use it or provide alternatives. For example, it doesn't compare with 'send_message' or 'ask'. The guidance is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
send_messageA
Send an async message to another Claude Code session. It lands in that session's intercom inbox; the recipient reads it with read_messages on its next turn. Set deliver_live=true to also inject it immediately into the recipient's live tmux pane (this interrupts whatever it's doing).
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | recipient session id or 8-char prefix (from list_sessions) | |
| text | Yes | the message body | |
| deliver_live | No | if the recipient is live, also push the message into its terminal now |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description effectively conveys key behaviors: async delivery to an inbox, optional immediate injection via live tmux pane with interruption. It does not detail error conditions or prerequisites, but covers the core behavioral traits.
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 with no filler. The purpose is front-loaded, and every clause adds essential detail. Perfectly concise.
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 adequately explains the sending process and the recipient's experience. It covers the main use cases but omits details like return value or error handling, which are acceptable for a send operation.
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 the description adds limited value beyond schema. It clarifies that 'to' can be an 8-char prefix and that deliver_live interrupts the recipient, matching schema descriptions.
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 action ('Send an async message') and the resource ('another Claude Code session'), immediately distinguishing it from siblings like list_sessions, read_messages, and reply.
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 when to use the tool (to send a message to another session) and mentions the alternative (read_messages for the recipient). It also describes the optional deliver_live parameter's effect, but lacks explicit 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
whoamiA
Identify which Claude Code session this is (its id, project, and cwd). Useful so other sessions can message you back.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full weight. It discloses that the tool returns identity information (id, project, cwd) with no side effects, which is transparent and accurate.
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, front-loaded with purpose, and contains no extraneous information. 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?
Given the tool's simplicity (no parameters, no output schema), the description is complete. It explains what the tool does and why it's useful.
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?
The tool has no parameters, so the baseline is 4. The description does not need to add parameter information, and it correctly omits any.
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 returning the current session's id, project, and cwd. It distinguishes itself from sibling tools like ask, send_message, and list_sessions, which serve communication or listing purposes.
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 states the tool is useful for other sessions to message you back, implying its use case. It does not explicitly list when not to use, but the context is sufficient for such a simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
6 tool updates
v0.1.0- First observed
ask - First observed
list_sessions - First observed
read_messages - First observed
reply - First observed
send_message - First observed
whoami
TDQS
Each tool targets a distinct action: listing sessions, asking live sessions, reading messages, replying, sending async messages, and identifying the current session. Even though 'send_message' with deliver_live=true overlaps with 'ask' in interrupting a session, the synchronous vs async distinction is clear.
Most tools use a verb_noun pattern (list_sessions, read_messages, send_message) but two are single verbs (ask, reply) and whoami is a fixed phrase. The naming is clear and follows imperative verbs, but the pattern isn't perfectly uniform.
6 tools is a well-scoped set for intercom functionality across Claude Code sessions. Each tool serves a necessary role without redundancy or excessive specialization.
The set covers core operations: discover sessions, communicate (ask, send, reply, read), and identify self. Missing a 'peek' or 'list messages' without marking read, but this is a minor gap for the domain.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Let your AI sessions talk to each other — messaging, tasks, sessions, and alerts
Collaboration layer for AI agents. Publish assets, send messages, manage threads and contacts.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables multiple Claude Code sessions to communicate and coordinate through broadcast and peer-to-peer messaging.21MIT
- AlicenseNot gradedqualityAmaintenanceEnables multiple Claude Code sessions to communicate and share results automatically, with optional orchestration for hands-off workflow coordination.15MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code instances to discover and communicate with each other across different sessions, supporting peer-to-peer messaging and coordination.34MIT
- AlicenseNot gradedqualityBmaintenanceEnables inter-session messaging for Claude Code, allowing sessions on different machines to send messages to each other, with delivery as user turns and support for offline queuing.431MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/AriOliv/claude-intercom'
If you have feedback or need assistance with the MCP directory API, please join our Discord server