Codex Intercom

Codex Intercom

Agent Intercom is a cross-harness, same-machine messaging system for coding agents. Its Pi, Codex, Claude Code, and OpenCode adapters share one local broker and protocol, so sessions can discover and message each other regardless of which harness they run in.

Maintenance & Upstream Provenance

• Maintained by ctliz: This distribution is maintained independently by ctliz.
• Upstream Heritage: Agent Intercom grew from Nico Bailon's original pi-intercom and the upstream dataforxyz/agent-intercom-* repositories. This project is not officially endorsed by or affiliated with upstream organizations.
• Package Namespace: The canonical npm namespace is @ctliz/*. The historical @dataforxyz/* namespace was used up to and including connect.1 and is retained only as provenance and as a migration-detection input; it is never treated as a current or healthy installation. The Agent Intercom branding and the intercom_* API surface are unchanged.

Protocol v4 & Broker-Enforced Scope

Agent Intercom protocol v4 introduces broker-enforced scope routing via AGENT_INTERCOM_SCOPE_ID:

• Registration: The client submits its scopeId once in the top-level registration payload.
• Broker Enforcement: The shared local broker stores the scope in its private ConnectedSession record and enforces same-scope discovery (intercom_list), naming, and prefix matching.
• Cross-Scope Routing: Cross-scope messaging is fail-closed; communication across different scopes is permitted only when addressing an explicit full session ID.
• UX Routing Isolation: Scope is designed for same-OS-user workflow isolation (e.g. per-project or per-workspace agent teams), not as a cryptographic security principal, tenant boundary, or authentication credential.
• Leak-Free: The raw scopeId value never enters SessionInfo, list payloads, lifecycle events, frontend displays, or execution logs.
• Standalone First: AGENT_INTERCOM_SCOPE_ID is a general shell/IDE/service launcher contract. Agent Intercom works completely standalone in any terminal, tmux window, or script; TmuxDeck is optional visual tooling.

Origin and thanks

Agent Intercom grew from Nico Bailon's original pi-intercom. A sincere thank you to Nico and the original contributors for creating the Pi extension and the foundation this cross-harness family builds on.

This repository contains the Codex adapter. It gives Codex sessions native intercom tools and wakeable workers while remaining fully interoperable with the other Agent Intercom harnesses.

The bundled client and broker use strict intercom protocol v4. A send is onlyreported as delivered after the receiving adapter acknowledges it. Unfinishedoutbound sends are persisted under the shared intercom runtime directory andreplayed with their original IDs after reconnect, making retries safe withreceiver deduplication. Incompatible older local brokers fail closed withoutkilling, downgrading, or creating second islands.

The project has two related pieces:

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

Use plain MCP when you only need tools inside an already-active Codex turn. Usecoi when you want another session to wake the worker automatically or whenyou want the host-level Alt+I and Alt+M shortcuts. Codex's MCP interface canprovide intercom tools, but it cannot add custom keybindings to the Codex TUI.

Status

Preview. This is the Codex adapter in the cross-harness Agent Intercom family.

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

When an external intercom turn completes, coi refreshes the attached remoteTUI by resuming the same thread. The inbound message and final response thenappear in the already-open terminal instead of existing only in the savedtranscript. This refresh happens after the turn is idle so Codex does not reopenin a phantom Working state. Retryable app-server stream errors are reported as reconnecting without terminating the sidecar, allowing Codex's own retry to complete. Orchestrated fresh: true launches remove the saved coi thread state before registration.

The additive Stage-B boss-run-v1 adapter contracts are present but dormant.Ordinary local and remote-access communication continues to use the existingprotocol-v4 behavior when Boss metadata is omitted. The legacy broker does notadvertise or bind Boss participants until a protected provider supplies all ofthe required broker identity, credential-registry, authority-transition, andparticipant-health predicates. Boss-scoped discovery and routing fail closedacross ordinary sessions and other Boss runs. The boss_participant andboss_reviewer launch-profile markers make production Codex launches failwith PROVIDER_AUTHORITY_UNAVAILABLE: this adapter has no broker-owned,artifact-attested provider executable and therefore never resolves protectedlaunches through caller PATH. Their non-spawning parser validators stillreject disabled approvals and danger-full-access, and reviewers remainread-only. The markers do not install or advertise a restricted operation client.Restricted Boss operation clients are not advertised or exported yet. Theyremain unavailable until the protected broker can provision both the bindingand transport through a non-caller-forgeable factory.

Install

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

git clone --depth 1 --branch v0.11.0-connect.2 https://github.com/ctliz/agent-intercom-codex.git
cd agent-intercom-codex && npm ci && npm link

The public npm package @ctliz/agent-intercom-codex is not yet published. GitHub at the exact connect tag is the only supported install path for this release.

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 intothe MCP server process. Configure identity on the MCP server entry when you needstable names or IDs.

To let a Pi manager create Codex workers with owned systemd cgroups, leases, model/effort selection, logs, and verified cleanup, install the companion Pi packages:

pi install git:github.com/ctliz/[email protected]
pi install git:github.com/ctliz/[email protected]

Restart Pi or run /reload, then call agent_fleet({ action: "doctor" }). The orchestrator invokes the installed coi command, or a separately configured minimal wrapper such as coim; it does not replace this Codex adapter.

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 usefulwhen you want Codex to install and manage the intercom integration as a plugin.For a deliberately minimal profile, prefer direct MCP configuration withcodex-intercom-mcp; that lets you disable plugins and skills while keeping theintercom tools.

Tools

• intercom_whoami: show this session's intercom ID, name, cwd, and model.
• intercom_team: show the current manager and live coworkers owned by that manager.
• intercom_status: show connection status and pending message counts.
• intercom_list: list local Pi, Codex, Claude Code, and OpenCode sessions in your scope (protocol v4 is same-scope; cross-scope contact requires an exact full session ID).
• 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; use to plus which: "oldest" | "latest" if one sender has multiple unresolved asks.

Pending output never exposes protocol message IDs. Keep at most one unresolved intercom_ask to the same recipient; the broker rejects a second ask and recommends intercom_send for a non-blocking follow-up. Use intercom_send—not intercom_ask—for assignments and progress/status checkpoints.

Persistent Codex bridges and plain MCP runtimes automatically reconnect their stable Intercom identity after a broker restart, so a live worker does not need to be respawned merely to become reachable again.

Example:

intercom_team({})
// Manager: manager-id [connected]
// You: worker-a
// Coworkers: reviewer target=reviewer (claude, challenger, running) [connected]

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 sidecarfor that socket, creates or resumes the sidecar's app-server thread, thenlaunches an interactive Codex UI attached to the same socket and thread.

Start a named worker:

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

If you launch wakeable workers often, a shell alias keeps coi distinct from aplain codex session:

alias codex-intercom='coi'

Then run codex-intercom --name worker-a --id worker-a. The alias is optional;the important part is launching through coi, because the wrapper owns theapp-server sidecar that wakes on incoming work and the terminal integrationthat provides Alt+I and Alt+M. Starting codex directly with only the MCP serverstill provides intercom tools, but not those host-level behaviors.

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 tocodex resume --remote, so normal Codex flags still work. Prompt arguments areplaced after the resumed sidecar thread ID.

While the coi TUI is open, press Alt+I to copy a short handoff snippet forthe current intercom session. As in pi-intercom, the snippet uses the uniquesession name when possible and falls back to the stable intercom session ID.The shortcut is provided by the coi launcher; plain MCP-only Codex sessions donot have a plugin API for custom TUI actions.

Press Alt+M to insert the Codex intercom session-picker request. Codex willcall intercom_list, show the available sessions, ask which peer and messageyou want, then use intercom_send. Codex does not expose native slash-commandor overlay registration, so coi provides this assisted flow instead ofclaiming a native /intercom command. The equivalent MCP tools remainavailable directly in every Codex session.

The shortcut uses native clipboard helpers locally and OSC 52 for SSH sessions.If clipboard access fails, coi inserts the snippet into the Codex composer.Disable the PTY-backed shortcut with --no-intercom-shortcut orCODEX_INTERCOM_SHORTCUT=0. The optional node-pty dependency is only loadedwhen the shortcut is enabled in an interactive terminal; if it is unavailable,coi launches the normal Codex TUI without the shortcut.

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

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

Every packaged executable writes one machine-searchable identity line to stderrbefore application startup:

[agent-intercom-build] package=@ctliz/agent-intercom-codex version=0.11.0-connect.2 target=coi sourceSha256=<64-hex-source-identity>

dist/build-info.json records the same deterministic runtime-source identity.Use the line from the actual process journal—not the current file path ormtime—to prove which bundle a remote worker loaded. Test-only changes do notalter the identity; any runtime, build-script, package, or pinned-dependencychange does.

Minimal Wakeable Profile

A minimal profile is useful for workers that should stay focused on code andcoordination. It reduces prompt/tool surface area by isolating the worker fromyour normal Codex config, memories, plugins, browser surfaces, image generation,and extra skills. Keep goals and multi-agent support on so the worker can trackthe 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 alternatehome. To keep the profile minimal without deleting anything, list the skillpaths:

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 minimalworker 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 approvalprompts and no filesystem sandbox. Use it only for workers you trust with thecurrent machine account, or remove the bypass flag when you want a saferworkspace-scoped worker. Use cim safe ... or set CODEX_YOLO=0 to launchwithout 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 thepackage, 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/agent-intercom-codex}"
  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 wakeableworkers. The manager keeps the task shaped, feeds work to workers, watches fordrift, 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 adecision the manager needs before continuing, use intercom_ask.

App-Server Bridge

Use codex-intercom-bridge when you want one process to publish one or moreconfigured virtual Codex workers without launching an interactive TUI for eachworker.

Create a bridge config:

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

Start it:

codex-intercom-bridge --config "$HOME/.config/codex-intercom/bridge.json"

Then other local sessions can target codex-worker with intercom_send orintercom_ask. The bridge stores each worker's app-server threadId instatePath, 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 inthe agent config only when you explicitly want a background worker to have moreauthority.

Development

Clone and run from source:

git clone https://github.com/ctliz/agent-intercom-codex.git
cd agent-intercom-codex
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.

Agent Intercom Compatibility

agent-intercom-pi is the Pi-native adapter with overlays, inline rendering,and Pi triggerTurn delivery. This repository, agent-intercom-codex, is theCodex MCP/plugin adapter plus wake-on-message Codex app-server sidecars. TheClaude Code and OpenCode adapters join the same broker and appear in the samesession list.

All four repositories vendor the compatible local broker/client protocol so anyadapter can start the broker and communicate across harness boundaries.

Releasing

Releases are automated from version tags. Update package.json, the lockfile whenpresent, and CHANGELOG.md on main, then push an annotated tag that exactlymatches the package version:

git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z

The release workflow verifies that the tag points into main, runs typecheck,tests, and the build, publishes the public npm package with trusted OIDCprovenance, and creates the GitHub Release. Existing npm versions and GitHubReleases are skipped safely when a workflow is rerun.

Compatibility, Migration & Rollback

• Single Shared Broker: The broker-capable adapters on the machine — pi, claude, codex, and opencode — connect to one local broker over a Unix domain socket (~/.pi/agent/intercom/broker.sock or $PI_CODING_AGENT_DIR/intercom/broker.sock).
• Coordinated Upgrade Set: Protocol v4 changes broker negotiation, so the broker-capable adapters that are actually installed and enabled on this machine must be upgraded together in one maintenance window. Adapters you do not use do not need to be installed to satisfy the upgrade. @ctliz/agent-intercom-core is an internal dependency that arrives with the adapters and is never installed or upgraded on its own.
• Orchestrator is Optional: agent-intercom-orchestrator is an optional Linux/systemd lifecycle component. It does not implement or start a Broker and is not part of the Broker compatibility set. Omitting it — for example on macOS, or when using TmuxDeck — is a fully supported configuration and is not a mixed or unsupported state. If it is installed on a supported Linux host, or on WSL with a systemd user manager enabled, update it together with the adapters it manages.
• Fail-Closed Legacy Handling: An incompatible legacy (v3) broker or client fails closed. It is rejected at negotiation and never killed, never downgraded, and never allowed to form a second broker island.
• Rollback: Rolling back covers only the components that were actually installed on this machine before the upgrade. Restore the exact specs and lockfiles you backed up, then reload the affected agent sessions. Roll Orchestrator back only if it was installed to begin with. There is no published pre-v4 tag under ctliz, so a pre-upgrade backup of the exact installed specs/locks is the supported rollback material. Leaving some installed broker-capable adapters on the old protocol while others are upgraded is an unsupported mixed state.

License

The current project is licensed under the GNU Affero General Public Licensev3.0 or later (AGPL-3.0-or-later). If you modify this software andmake the modified version available to users over a network, the AGPL requiresyou to offer those users the corresponding source code.

Portions derived from the original MIT-licensed pi-intercom project retaintheir original notices. See THIRD_PARTY_NOTICES.md andlicenses/MIT-pi-intercom.txt. Versions alreadypublished under MIT remain available under their original terms. SeeLICENSE_TRANSITION.md for the exact commit and tag boundary.

Upgrading from connect.1 to connect.2

connect.2 renames the package namespace from @dataforxyz/* to @ctliz/*. The two namespaces are different packages to npm. Pi Git package installations deduplicate by repository URL without ref, but running agent sessions continue to execute legacy code in memory, and npm or global installs along with binary links can coexist and conflict. Operators must stop active sessions, clean active install surfaces, and follow remove-before-install — side-by-side installation is not supported.

1. Back up the exact specs, lock files, and settings of every installed component.
2. Stop or close the installed broker-capable adapters.
3. Remove the old @dataforxyz/* specs, packages, and binary links that are actually installed.
4. Assert the old identity is gone from the active install surfaces of the current OS user: Pi settings and extension specs, resolved managed install roots, actual node_modules installations, and conflicting binary links that the current PATH would resolve. Do not scan or delete unrelated source checkouts, historical documentation, or other users' files — a @dataforxyz/* string in an unrelated development clone is not an installation.
5. Install the @ctliz/* connect.2 exact tags for the components you actually use (v0.11.0-connect.2).
6. Reload or restart, then verify exactly one broker is running.

Classification rule. Migration-aware connect.2 setup and update tooling must classify an old-namespace-only install surface as MIGRATION_REQUIRED, and the simultaneous presence of both namespaces as a duplicate/dual-load hard error that refuses setup, update, and further installation. This tooling does not exist for every platform and adapter combination; where it is not available, apply the same two rules manually against the surfaces in step 4. Do not assume every adapter emits this code automatically.

Rollback reverses this and covers only the components that were installed on this machine before the upgrade: remove the @ctliz/* packages, then restore the backed-up exact @dataforxyz/* specs and locks. Roll Orchestrator back only if it was installed to begin with.

The connect.1 tags, source commits, and published release assets are immutable and are not modified by this migration. Release notes may carry an explicit erratum, which corrects the description only and never moves a tag or replaces an asset.

These packages are not published on the npm registry yet; install from the GitHub tags shown above.