Skip to main content
Glama

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 now

  • whoami — find out which session you are

  • send_message — drop an async message into another session's inbox

  • read_messages — pick up messages other sessions sent you

  • reply — answer a message you received

  • ask — 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_sessions reads those for the session id, project, first prompt (as a title), and last-active time.

  • Liveness. A session is "live" if its claude process 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 claude process and uses lsof to find which transcript that process has open — that's you. (Override with CLAUDE_INTERCOM_SESSION if detection ever fails.)

  • Live delivery / ask. For a live target, the message is typed into its tmux pane with tmux send-keys. For ask, the server then tails the target's transcript and returns the assistant text that appears in response.

Heads up: live delivery and ask interrupt whatever the target session is doing, exactly as if you typed into its terminal. Async send_message (the default) does not — the recipient sees it when it next calls read_messages.

Related MCP server: claude-session-bridge

Requirements

  • Node.js ≥ 18

  • tmux, ps, and lsof on PATH (standard on macOS/Linux) — only needed for liveness, live delivery, and ask. Async messaging works without them.

Install

git clone https://github.com/AriOliv/claude-intercom
cd claude-intercom
npm install
npm run build

Then 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-intercom

Or 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

CLAUDE_CONFIG_DIR

~/.claude

Where Claude Code stores projects/ transcripts

CLAUDE_INTERCOM_DIR

~/.claude-intercom

Where messages are stored

CLAUDE_INTERCOM_SESSION

(auto)

Force this server's session identity (a session id)

CLAUDE_INTERCOM_RESUME_FLAGS

(empty)

Extra flags passed to claude -p --resume when ask reaches an idle session (e.g. --dangerously-skip-permissions). Empty = safe default.

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 tsx

Limitations

  • Liveness, live delivery, and ask assume sessions run inside tmux. Plain-terminal sessions still work for list_sessions and async send_message/read_messages.

  • ask reads 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 tools
askA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
toYestarget session id or prefix (must be live)
questionYesthe question to ask
wait_secondsNohow long to wait for an answer (default 90)

TDQS

A4.1/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
scopeNorecent = sorted by last activity (default), live = only running sessions, all = everything
projectNofilter by project name or path substring
limitNo

TDQS

A4.1/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
unread_onlyNoonly return messages you haven't read yet (default true)

TDQS

A4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
message_idYesthe message id (or prefix) you are replying to, from read_messages
textYesyour reply
deliver_liveNoalso push the reply into the sender's terminal if it is live (default true)

TDQS

A3.9/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesrecipient session id or 8-char prefix (from list_sessions)
textYesthe message body
deliver_liveNoif the recipient is live, also push the message into its terminal now

TDQS

A4.2/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

  1. 6 tool updatesv0.1.0
    • First observedask
    • First observedlist_sessions
    • First observedread_messages
    • First observedreply
    • First observedsend_message
    • First observedwhoami

TDQS

A4.1/5.0
Disambiguation5/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityStale
ResponsivenessNo issues

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

Related MCP Servers

Latest Blog Posts

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