Pi Conductor
Click on "Deploy 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., "@Pi Conductor spawn two dev workers to add auth plus tests, then review and merge the diffs"
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.
Pi Conductor for Codex
The Codex sister project of omp-conductor, adapted from its pi-backend branch. Codex orchestrates persistent Pi RPC workers through a local MCP server. Workers implement, investigate or review; Codex inspects reports and real diffs before merging.
The projects are maintained separately: omp-conductor serves Claude Code; omp-conductor-codex serves Codex. Shared Pi worker concepts and fixes can move between them under the MIT license. This is a standalone repository, rather than a GitHub fork tied to the original branch history. This package has no Claude runtime, React pane, Haiku call, shell stdin wrapper or Claude hook dependency.
Install
Requires Node 22.19+, Git, and Pi on PATH. The optional companion launcher also requires tmux and a current Codex CLI with --no-daemon. The toolbox runner uses Linux bash, timeout and flock (matching the upstream Linux workflow).
Install the prebuilt plugin directly from GitHub:
codex plugin marketplace add SamiulH25/omp-conductor-codex --ref main
codex plugin add omp-conductor-codex@omp-conductor-codexStart a new Codex session to load the tools and skill. The committed dist/server.mjs bundles the server dependencies; installation does not require npm or a build step.
If Pi is not installed yet:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --versionTo install from a local checkout instead:
git clone https://github.com/SamiulH25/omp-conductor-codex.git
cd omp-conductor-codex
codex plugin marketplace add .
codex plugin add omp-conductor-codex@omp-conductor-codexA minimal plugin ZIP is also available from GitHub Releases. Extract it, run codex plugin marketplace add /absolute/path/to/omp-conductor-codex, then use the same codex plugin add command above. Keep API keys in your environment or local worker data directory; do not add them to this checkout.
Pi workers use OpenCode Go by default. Export OPENCODE_GO_API_KEY in the environment Codex starts from, or put OPENCODE_GO_API_KEY=... in ~/.codex/plugin-data/omp-conductor-codex/env with mode 600. The legacy ~/.pi-workers/env file is also read if the new file is absent. The key is passed only to Pi; it is never returned in status or reports. No OpenAI API key is needed.
The server creates its worker settings, model definition and session directories on first use. OMP_CONDUCTOR_DATA_DIR overrides the data directory. Its startup check probes Pi and credentials without making an inference request.
Related MCP server: codex-supervisor-mcp
Companion split
Launch Codex with the live dashboard beside it:
./bin/conductor -- -C /path/to/your/projectFrom an installed GitHub plugin, use the bundled launcher:
~/.codex/plugins/cache/omp-conductor-codex/omp-conductor-codex/1.1.0/bin/conductor -- -C /path/to/your/projectNo build is needed. If tmux is missing, install it first (sudo apt install tmux on Ubuntu/Debian). The launcher creates a tmux session, or adds a sidebar to the current pane when already inside tmux. Codex receives any arguments after --. It uses --no-daemon so the MCP server inherits the panel ID and data directory even if another Codex daemon is already running.
Use Ctrl-b then Left/Right to switch panes with default tmux bindings. Press q in the dashboard to close that pane; j/k or Up/Down scroll its cards. The sidebar also closes when Codex exits. Ctrl-b then d detaches a newly created session; the launcher prints an attach command when used with launch --detach --.
The dashboard shows animated worker faces and spinners, states, activity, files touched, elapsed time, a time-budget bar, token rates and sparklines, cost, errors and verification warnings. Flat-rate usage is labeled plan. Snapshots are refreshed without model calls, are scoped to each launch, and stay private under the worker data directory. If the server stops updating, active workers are shown as interrupted rather than as live work.
Preview the UI or inspect existing snapshots:
./bin/conductor dashboard --demo
./bin/conductor dashboard --once
./bin/conductor dashboard --data-dir /path/to/worker-dataA standalone dashboard shows recent sessions across launch groups. The split launcher selects only its own group. The plugin installed in Codex must be v1.1.0 or newer to publish dashboard snapshots; update it using the commands below and start a new session. The launcher can also be run directly from the extracted release ZIP.
Use
Ask Codex: “Use Pi Conductor to split this implementation into independent worker tasks, review their changes, and merge the accepted work.” The bundled orchestrate-pi skill covers briefing, checks and the review loop.
Tools | Purpose |
| Start a worker or recall it with context retained |
| Activity, token/cost metrics, completion and reports |
| Review real changes and merge an accepted branch |
| Stop work; remove an idle worker and its worktree |
| Project glossary and runnable verification checks |
| Show/change settings with optional |
explore and review workers have read-only tools. dev and general workers default to isolated worktrees in git repositories. Non-git tasks run in place with snapshots for file-tool edits. A maximum of four workers runs per server session.
Workers get a soft time warning, a partial-report request and a hard stop after a grace period. Expected-file and verification warnings remain visible in digests. Toolbox checks can serialize across workers; supervisor verification supports bounded fix rounds. Detailed investigation/review reports are preserved rather than compressed by another model.
Merges refuse tracked changes in the main checkout, abort main-checkout conflicts and hand conflicts to the worker worktree. Cleanup refuses unmerged changes unless force: true is explicitly used. Worktrees and the path guard are accident-prevention measures, not a security sandbox: editing workers can run shell commands as the current user. Workers do not automatically load project instruction files; include the applicable instructions in their briefs.
State and host differences
State is stored separately from the Claude version in the Codex data directory. With CODEX_THREAD_ID, a restart reloads that thread's worker records and Pi session IDs. Without it, each MCP process uses a fresh UUID so separate clients do not share workers. An interrupted worker can resume through pi_send when its saved Pi session is available. Model, effort, dictionaries and toolboxes persist across sessions.
The Claude embedded pane is replaced by the companion tmux dashboard; Codex still uses pi_status and bounded pi_wait to review workers. No unsupported Codex UI hooks are installed. The dashboard is read-only: worker corrections, merging and cleanup remain MCP operations inside Codex.
Development and validation
npm ci --ignore-scripts
npm test
npm run dashboard -- --demo
npm run package # clean ZIP under artifacts/, with no node_modules or development filesTests use a local fake Pi executable and real Git repositories. They cover isolated edits, recall, reviewed new-file diffs, merge/cleanup, concurrent limits, crashes, verification failures, merge conflicts, and MCP initialization/input validation. They also check live snapshot updates, session isolation, stale-server indicators, terminal escape sanitization, and real tmux splits both outside and inside an existing session. They do not spend model credits. npm run build type-checks TypeScript and bundles the server with esbuild.
The host-independent worker engine and Pi guard/toolbox are adapted from upstream commit 8bca6ad under the included MIT license. Codex packaging follows OpenAI's plugin documentation.
Updating
Refresh the GitHub marketplace and reinstall the plugin to pick up new files, then start a new session:
codex plugin marketplace upgrade omp-conductor-codex
codex plugin add omp-conductor-codex@omp-conductor-codexSister-project maintenance
Report Codex packaging, MCP, or runtime issues here. Report issues in the original Claude host integration to omp-conductor. When porting a shared worker-engine fix, cite the source commit and preserve the MIT copyright notice. Neither project's working directory or release process depends on the other repository.
Available Tools
13 toolspi_cleanupA
Remove a finished worker's worktree and branch and forget the worker. Refuses if it has unmerged work unless force is true.
Inputs: id (required), force.
pi_dictA
The project dictionary: short term -> definition entries (what a system is called, what it does, where it lives, conventions) that are injected into every worker for that project. Seed it from what you already understand BEFORE the first pi_spawn; after reviewing a worker, add facts you verified (never unverified worker claims). Not for task notes or history. action: show | set (upsert entries) | remove (terms).
Inputs: action (required), dir, terms, entries.
pi_diffB
git diff (with stat) of a worker's directory so you can review the real changes.
Inputs: id (required), maxChars.
pi_digestA
Compact report of one worker: files changed, commands, errors, final message, git status. detail "full" adds recent raw events. Treat claims as unverified; check with pi_diff.
Inputs: id (required), detail.
pi_effortB
Show or change the reasoning effort every Pi worker uses
Inputs: value.
pi_killC
Abort a running worker and stop its Pi process.
Inputs: id (required).
pi_mergeA
Commit a finished worker's worktree changes and merge its branch (--no-ff) into the repo it was spawned from. Refuses while the worker runs or the main tree has tracked changes; aborts and reports on conflict.
Inputs: id (required), message.
pi_modelC
Show or change the model every Pi worker uses
Inputs: value.
pi_sendA
Send a follow-up message to a finished worker. Its Pi process (or, after 30 idle minutes, its saved session) keeps everything it already read, so use this for fixes and for the next task in the same area instead of re-spawning (no re-reading, no re-learning the layout). Send only the new instruction; it already has the background. The worker must not be running.
Inputs: id (required), message (required), effort, maxMinutes.
pi_spawnA
Start a Pi worker in the background on a self-contained task and return its id at once. Workers always use the model the user set with pi_model (not selectable here). Give it a complete standalone brief (it has no access to this conversation). Use disjoint dirs or let worktree isolation separate parallel workers. Then use pi_wait / pi_digest to read compact results and judge them. Workers are long-lived RPC processes that keep their context: for a fix or a follow-up in the same area, pi_send an existing worker instead of spawning a new one.
Inputs: task (required), dir, agent, title, +9 more.
pi_statusB
One line per worker: state, elapsed, last action, files touched.
Inputs: no named parameters.
pi_toolsA
The project toolbox: the checks (tests, compile, lint) workers are expected to run THEMSELVES with check <name> before reporting. Shown in every dev/general worker's prompt; required checks are enforced (the worker is reminded, and the digest warns if one was not run or failed). serial checks hold a project-wide lock, so a tool that cannot run twice at once (a Unity editor, a Gradle daemon) is safe with parallel workers: do not forbid workers from running it. A Unity project with no toolbox set gets built-in unity-editmode (required) and unity-playmode checks. action: show | set (upsert checks) | remove (names) | reset (drop all, back to the built-in default).
Inputs: action (required), dir, names, checks.
pi_waitA
Wait until the given workers (default: all running) finish or timeoutSec passes (max 60 per call; call again to keep waiting), then return their digests.
Inputs: ids, mode, timeoutSec.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools have a clearly distinct lifecycle role (spawn, kill, merge, cleanup, send). There is mild overlap in reporting: pi_wait, pi_digest, and pi_status all surface worker state/digests, though the blocking-vs-snapshot distinction is described well enough to disambiguate.
Every tool uses a uniform pi_ prefix with a short, readable suffix. Action verbs (spawn, wait, send, kill, merge, cleanup) and config nouns (dict, tools, model, effort, status) are used consistently within their categories.
13 tools is well-scoped for a worker-orchestration server, covering the full lifecycle without redundant entries. Each tool earns its place (lifecycle ops, config, and two project-context stores).
The surface covers the whole worker lifecycle: spawn, monitor (wait/digest/status), review (diff), follow-up (send), abort (kill), integrate (merge), and teardown (cleanup), plus model/effort config and shared project context. No obvious gaps or dead ends.
Maintenance
Related MCP Connectors
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Build, test, publish, and run Kovca workflows from AI agents over remote MCP.
Command center for developers coordinating AI coding agents across projects.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAn MCP server for orchestrating a fleet of CLI coding agents in isolated git worktrees. It exposes tools for spawning workers, sending instructions, reviewing diffs, and merging changes, with full terminal visibility.7 npm4MIT
- AlicenseNot gradedqualityBmaintenanceEnables a primary agent to dispatch, wait on, and supervise multiple parallel Codex CLI workers, each running in its own isolated Git worktree with conflict-checked path ownership. Persists every worker's state, goals, and event stream to disk so work can be tracked, resumed, reconnected, searched, and cancelled across restarts.433 npm3MIT
- AlicenseNot gradedqualityAmaintenanceEnables Codex to supervise one or more local Pi coding-agent workers through bounded task execution, state polling, steering, aborting, and listing. Tasks can run in a direct working directory or isolated Git worktree while Codex remains the planner and reviewer.MIT
- AlicenseNot gradedqualityBmaintenanceEnables Codex conversations to delegate tasks to persistent worker subagents backed by models configured in VS Code, including BYOK endpoints. Provides workspace inspection and controlled editing tools, approval-gated shell commands, transcripts, and worker lifecycle management.1MIT