Codex Intercom

Codex Intercom adds local messaging between Codex, Pi, and other coding-agent sessions on the same machine. It speaks the same local broker protocol as pi-intercom, so sessions can discover each other, send updates, ask blocking questions, read pending messages, and reply to asks.

The project has two related pieces:

• codex-intercom-mcp: an MCP server that exposes intercom tools inside a normal Codex session.
• coi: a wakeable Codex sidecar launcher. It starts a Codex app-server, registers an intercom identity, and starts Codex turns when another session sends it work.

Use plain MCP when you only need tools inside an already-active Codex turn. Use coi when you want another session to wake the worker automatically.

Status

Preview. This is the Codex-side adapter split out of pi-intercom.

Plain Codex MCP sessions do not receive Pi-style unsolicited visible turns. Incoming messages are queued while the MCP server is running; call intercom_pending to read them. Wake-on-message workflows require coi or the app-server bridge.

Install

For normal use, install the package so the command-line entry points are on PATH:

npm install -g github:dataforxyz/codex-intercom

This provides:

• codex-intercom-mcp
• codex-intercom-bridge
• coi

Then add the MCP server to Codex:

codex mcp add codex-intercom -- codex-intercom-mcp

Optional MCP identity variables can be attached at registration time:

codex mcp add codex-planner \
  --env CODEX_INTERCOM_NAME=planner \
  --env CODEX_INTERCOM_SESSION_ID=codex-planner \
  --env CODEX_INTERCOM_MODEL=codex \
  -- codex-intercom-mcp

Per-command environment variables passed to codex exec are not forwarded into the MCP server process. Configure identity on the MCP server entry when you need stable names or IDs.

Plugin Use

This repo also includes Codex plugin metadata:

• .codex-plugin/plugin.json
• .mcp.json
• skills/codex-intercom/SKILL.md

The plugin packages the MCP server and the optional intercom skill. It is useful when you want Codex to install and manage the intercom integration as a plugin. For a deliberately minimal profile, prefer direct MCP configuration with codex-intercom-mcp; that lets you disable plugins and skills while keeping the intercom tools.

Tools

• intercom_whoami: show this session's intercom ID, name, cwd, and model.
• intercom_status: show connection status and pending message counts.
• intercom_list: list local Pi and Codex sessions.
• intercom_set_summary: publish a short discoverable status.
• intercom_send: send a non-blocking message.
• intercom_ask: send a question and wait for the target's reply.
• intercom_pending: read queued inbound messages and unresolved asks.
• intercom_reply: reply to a pending inbound ask.

Example:

intercom_list({ scope: "machine" })

intercom_ask({
  to: "worker-a",
  message: "Please inspect the failing test and reply with the likely cause.",
  timeout_ms: 45000
})

Blocking asks default to a short bounded wait and reject waits over 120 seconds. For longer work, use intercom_send and check later with intercom_pending.

Wakeable Workers With coi

coi starts a per-agent Codex app-server socket, registers an intercom sidecar for that socket, creates or resumes the sidecar's app-server thread, then launches an interactive Codex UI attached to the same socket and thread.

Start a named worker:

coi --name worker-a --id worker-a

Useful flags:

coi --name api-worker --id api-worker
coi --cwd /path/to/project --instructions "Reply tersely. Ask before destructive changes."
coi --no-tui --name background-worker --id background-worker

Everything not recognized as a sidecar flag is passed through to codex resume --remote, so normal Codex flags still work. Prompt arguments are placed after the resumed sidecar thread ID.

coi also applies Codex runtime flags such as --sandbox, --ask-for-approval, and --add-dir to wake-triggered sidecar turns. For example, coi --name worker-a --id worker-a --sandbox workspace-write lets intercom-woken turns write inside the worker workspace instead of falling back to read-only.

The sidecar inherits CODEX_HOME, which makes it useful with a normal Codex home or a dedicated minimal home.

Minimal Wakeable Profile

A minimal profile is useful for workers that should stay focused on code and coordination. It reduces prompt/tool surface area by isolating the worker from your normal Codex config, memories, plugins, browser surfaces, image generation, and extra skills. Keep goals and multi-agent support on so the worker can track the task and delegate subtasks.

Create a dedicated Codex home:

export CODEX_MIN_HOME="$HOME/.codex-min-intercom"
mkdir -p "$CODEX_MIN_HOME"

$CODEX_MIN_HOME/config.toml:

model = "gpt-5.5"
web_search = "disabled"

[features]
apps = false
memories = false
web_search = false
web_search_cached = false
web_search_request = false

# Keep the core coding-agent surface.
goals = true
multi_agent = true
shell_tool = true
unified_exec = true
auto_compaction = true
tool_call_mcp_elicitation = true

# Disable optional/distraction-heavy surfaces.
browser_use = false
browser_use_external = false
browser_use_full_cdp_access = false
in_app_browser = false
computer_use = false
image_generation = false
plugins = false
plugin_sharing = false
tool_suggest = false
skill_mcp_dependency_install = false
hooks = false
workspace_dependencies = false

[mcp_servers.codex-intercom]
command = "codex-intercom-mcp"

After the first launch, Codex may populate system skills under the alternate home. To keep the profile minimal without deleting anything, list the skill paths:

find "$CODEX_MIN_HOME/skills" -name SKILL.md -print

For each skill you want disabled, add a config entry:

[[skills.config]]
path = "/absolute/path/from/find/SKILL.md"
enabled = false

There is no required alias name. A short alias such as cim keeps the minimal worker easy to launch:

cim() {
  local home="${CODEX_MIN_HOME:-$HOME/.codex-min-intercom}"
  local yolo="${CODEX_YOLO:-1}"
  case "${1:-}" in
    yolo|--yolo|on) shift; yolo=1 ;;
    safe|--safe|off) shift; yolo=0 ;;
  esac
  local args=(--name codex-min)
  [ "$yolo" = 1 ] && args+=(--dangerously-bypass-approvals-and-sandbox)
  CODEX_HOME="$home" coi "${args[@]}" "$@"
}

This alias intentionally defaults the minimal worker to yolo mode: no approval prompts and no filesystem sandbox. Use it only for workers you trust with the current machine account, or remove the bypass flag when you want a safer workspace-scoped worker. Use cim safe ... or set CODEX_YOLO=0 to launch without the bypass flag.

Use it like:

cim --name worker-a --id worker-a
cim --name reviewer --id reviewer --instructions "Review only; do not edit files."
cim --no-tui --name background-worker --id background-worker
cim safe --name safe-worker --id safe-worker --sandbox workspace-write

If you are developing this repository from a checkout instead of installing the package, build and link it:

npm install
npm run build
npm link

Or point an alias directly at the checkout:

cim() {
  local home="${CODEX_MIN_HOME:-$HOME/.codex-min-intercom}"
  local repo="${CODEX_INTERCOM_REPO:-/absolute/path/to/codex-intercom}"
  local yolo="${CODEX_YOLO:-1}"
  case "${1:-}" in
    yolo|--yolo|on) shift; yolo=1 ;;
    safe|--safe|off) shift; yolo=0 ;;
  esac
  local args=(--name codex-min)
  [ "$yolo" = 1 ] && args+=(--dangerously-bypass-approvals-and-sandbox)
  CODEX_HOME="$home" node "$repo/dist/coi.mjs" "${args[@]}" "$@"
}

Manager And Worker Pattern

Use one Codex session as the manager and one or more coi sessions as wakeable workers. The manager keeps the task shaped, feeds work to workers, watches for drift, and decides when the work is ready to finish.

Example worker launch in tmux:

tmux new-session -d -s worker-a 'cd /path/to/project && cim --name worker-a --id worker-a'

Then ask the worker from the manager session:

intercom_ask({
  to: "worker-a",
  message: "Please create a goal for the task, inspect the handoff, and report your first plan.",
  timeout_ms: 45000
})

Recommended manager prompt:

Start a wakeable worker in tmux using the minimal intercom alias:

  tmux new-session -d -s <worker-id> 'cd <repo> && cim --name <worker-id> --id <worker-id>'

Give the worker a FEAT.md-style handoff:

# FEAT: <short task name>
Objective: <what must be true when done>
Context: <repo, branch, issue, constraints, important files>
Approach: <suggested first steps, but allow the worker to adjust>
Verification: <commands/tests/checks that should pass>
Definition of done: <clear finish criteria>
Coordination: create a goal, use subagents when useful, keep the manager updated through intercom, ask before risky or broad changes, and keep work in a branch/worktree when appropriate.

Tell the worker to create and maintain its own goal, use agents for parallel investigation or review, and report blockers early. As manager, keep sending focused follow-up work through intercom, keep the worker on task, and handle PR or final handoff when the implementation is ready.

For non-blocking delegation, use intercom_send and check back later. For a decision the manager needs before continuing, use intercom_ask.

App-Server Bridge

Use codex-intercom-bridge when you want one process to publish one or more configured virtual Codex workers without launching an interactive TUI for each worker.

Create a bridge config:

{
  "statePath": "/home/you/.pi/agent/intercom/codex-bridge-state.json",
  "agents": [
    {
      "id": "codex-worker",
      "name": "codex-worker",
      "cwd": "/home/you/src/project",
      "model": "gpt-5.5",
      "instructions": "Reply concisely. Ask before making destructive changes."
    }
  ]
}

Start it:

codex-intercom-bridge --config /home/you/.pi/agent/intercom/codex-bridge.json

Then other local sessions can target codex-worker with intercom_send or intercom_ask. The bridge stores each worker's app-server threadId in statePath, so later messages continue the same Codex thread.

By default, bridge turns run with approvalPolicy: "never" and read-only, network-disabled sandboxing. Override approvalPolicy or sandboxPolicy in the agent config only when you explicitly want a background worker to have more authority.

Development

Clone and run from source:

git clone https://github.com/dataforxyz/codex-intercom.git
cd codex-intercom
npm install
npm run build
npm test

For MCP development, register the TypeScript source directly:

codex mcp add codex-intercom-dev -- npx --no-install tsx ./codex/server.ts

Use either the built install or the dev install in a given Codex profile. Running both at the same time can register duplicate intercom MCP tools.

Relationship To Pi Intercom

pi-intercom remains the Pi-native extension with overlays, inline rendering, and Pi triggerTurn delivery. codex-intercom is the Codex MCP/plugin adapter plus wake-on-message Codex app-server sidecars.

For now this repository vendors the minimal local broker/client protocol for compatibility. If the protocol stabilizes across multiple adapters, the shared parts should move into a small core package.