swarm-mcp

name	swarm-mcp
description	Inspect the coordination MCP surface swarm-codex registers for role threads. Reports which daemons (opentasks, agent-inbox, minimem) are available, which are actually running, and what's wired into the per-run CODEX_HOME `config.toml`. Non-invasive — never modifies the user's `~/.codex/config.toml`.
user_invocable	true
argument	optional

/swarm-mcp — Inspect Coordination MCP Surface

Use this skill to audit which MCP servers swarm-codex makes available to role threads. swarm-codex registers up to three coordination MCPs in each per-run CODEX_HOME/config.toml — opentasks, agent-inbox, minimem — gated on whether their daemon binaries are installed AND (where applicable) reachable on a Unix socket.

What this is NOT

• Not an installer for the user's ~/.codex/config.toml. swarm-codex never modifies user-global Codex config; each run gets its OWN CODEX_HOME (under .swarm/codex-swarm/tmp/run/<runId>/codex-home/) where MCP servers are written transiently and torn down with the run.
• Not a permissions tool. Codex doesn't have a .claude/settings.local.json equivalent; tool approval is per-call via the TUI.
• Not a way to add custom MCP servers. Custom servers belong in the user's ~/.codex/config.toml; this skill reports the coordination set swarm-codex manages, not your own MCPs.

Subcommands

Parse $ARGUMENTS as the first token. With no argument, default to check.

check — Daemon availability + registration report (default)

Purpose: show which coordination daemons are installed, which are currently running, and what swarm-codex will register in a per-run CODEX_HOME.

Steps:

1. Run swarm-codex daemons status and parse its output:
   • opentasks: install status + daemon socket reachability
   • agent-inbox: same
   • minimem: install status (file-based, no daemon socket — only the binary needs to be findable)
2. Group results into:
   • ready[] — installed AND reachable; will be registered in CODEX_HOME on the next run.
   • installed-but-down[] — installed, daemon not running. Suggest swarm-codex daemons up.
   • missing[] — binary not on PATH. Suggest the npm install line for each.
3. Render a compact table. Do not write any files.

up — Start missing daemons (explicit)

Purpose: bring up the coordination daemons that are installed but not currently running.

Steps:

1. Confirm with the user before running. (swarm-codex daemons up can spawn long-lived background processes; users should know.)
2. Invoke swarm-codex daemons up.
3. Stream the output; report which daemons came up and which reported errors.
4. Re-run check semantics to show the new state.

print-config — Show the per-run config.toml shape

Purpose: dump the [mcp_servers.X] blocks swarm-codex would write for the next swarm-codex run invocation in this project. Useful for debugging "why is opentasks not visible to my role thread?".

Steps:

1. Find the most recent run dir under .swarm/codex-swarm/tmp/run/. If none exists, run a dry swarm-codex run --dry-run (if supported) OR direct the user to run a real swarm and then re-invoke this skill.
2. Open <latest-run>/codex-home/config.toml and pretty-print the [mcp_servers.*] blocks. Strip any credentials (env values) before showing.
3. Do not write or modify anything.

Default behavior when no subcommand given

If $ARGUMENTS is empty, run check — the safest and most informative default.

What you must NOT do

• Do not modify ~/.codex/config.toml (user-global Codex config).
• Do not modify any project-level .codex/ or .swarm/ files.
• Do not start daemons without explicit user confirmation for up.
• Do not invoke swarm-codex run from inside this skill — that's /swarm's job.

Why this exists

Codex's MCP UX is fundamentally different from Claude Code's:

Codex	Claude Code
~/.codex/config.toml (TOML)	.mcp.json (JSON, project-level)
Per-call tool approval via TUI	.claude/settings.local.json
CODEX_HOME env var override	(no equivalent)

cc-swarm ships a heavier /swarm-mcp that does install + permissions sync because Claude Code has those layers. For swarm-codex, the operational question is much narrower: "which coordination daemons are reachable, and what will my next run see?" This skill answers that without touching user config.