hierarchical-codex
This server is a deterministic MCP control plane that manages durable, policy-enforced missions and tasks for Codex subagents.
Create, read, and close missions with locked strategies, budgets, risks, and success criteria.
Allocate policy-checked tasks with roles, models, reasoning effort, dependencies, budgets, and parent-child hierarchy.
Claim, start, heartbeat, release, block, fail, cancel, and supersede tasks using leases and optimistic versioning.
Store and retrieve bounded, content-addressed artifacts.
Submit, check, verify, and commit results through producer/reviewer separation and evidence gates.
Enforce hierarchical token, cost, wall-time, tool-call, and child-count budgets.
Report usage atomically against missions and tasks with hard limit enforcement.
Recover durable mission state and audit events after interruptions or context compaction.
Support idempotent mutations and append-only audit logging for reliable workflow control.
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., "@hierarchical-codex Start a Sol/Terra/Luna mission to fix login bugs with a 20-minute budget."
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.
Agent Trio V3.5
Agent Trio V3.5 is a cost-aware multi-agent runtime built on Codex App Server. Its default
balanced profile lets the current Sol choose among root completion, one Luna/Terra execution
agent, and an economically admitted compact DAG. The quality profile preserves V3.3's always-delegate,
quality-first behavior. TypeScript handles concurrency, dependencies, budgets, recovery, and patch
integration after Sol makes the semantic decision.
The runtime is designed around three targets relative to direct gpt-5.6-sol/ultra:
cost at or below 40%;
elapsed time at or below 70%;
quality at or above 95%, or within 3 points.
The normal path contains no mission ledger, heartbeat loop, mandatory reviewer, audit chain, or user continuation gate.
Results
The V3.5 three-arm run covers 54 sealed tasks across 18 families: 54 direct
gpt-5.6-sol/ultra, 54 Balanced, and 54 Quality executions. Percentages are relative to direct Sol;
cost uses recorded App Server tokens and the configured price table.
All 54 tasks | Total time | Time vs Sol | Total cost | Cost vs Sol | Mean quality | Minimum |
Direct Sol | 3,593.7s | 100.0% | $3.1811 | 100.0% | 100.00 | 100 |
Balanced | 2,193.0s | 61.0% | $1.4419 | 45.3% | 98.98 | 67 |
Quality | 2,716.9s | 75.6% | $1.7083 | 53.7% | 98.22 | 67 |
On the 12 tasks whose calibration qualified them as economically decomposable, Balanced measured 60.5% of direct Sol time and 47.0% of its cost. Its quality was 98.98% of direct with a 1.02-point gap. Quality measured 53.9% time and 80.1% cost, with 98.22% relative quality and a 1.78-point gap.
Both profiles pass the overall, per-domain, and absolute quality gates. Balanced passes the 70% aggregate time gate but misses the 40% aggregate cost gate, per-family economic gates, 25% planning cost gate, 15% direct overhead gate, and compact-fanout routing gates. The run recorded zero protocol errors, user interventions, and critical failures. V3.5 therefore establishes the quality result and a substantial speed/cost reduction, while its Balanced routing still requires further cost and topology optimization.
The final scores were recalculated from the saved outputs after correcting false-negative wording and formatting rules. The offline pass made zero model calls, changed only 20 quality scores, and preserved all 162 timing and cost records. The full JSON report is attached to the v3.5.0 release.
See Benchmarking for calibration, the three-arm runner, evidence format, and scoring rules.
Related MCP server: nexo-agent-server
Install
Requirements:
Node.js 20 or newer.
A working Codex CLI with App Server support.
Access to the configured Luna, Terra, and Sol models.
Git for isolated parallel writers.
Install from the repository:
npm install
npm run check
npm run install:user
npm run doctor:userinstall:user performs two kinds of user-level change:
registers one
[mcp_servers.agent_trio]entry in~/.codex/config.toml;installs
$agent-trio,$agent-trio-session,$agent-trio-quality, and$agent-trio-quality-sessionunder~/.agents/skills.
The MCP launcher reads assignment-style *.env files directly under the active Codex home before
starting Agent Trio. This makes provider variables such as PRO_API_KEY available to Agent Trio and
its child App Server processes in the desktop app, VS Code, and CLI without storing credentials in
config.toml. Files are loaded in filename order; later assignments override earlier ones. The
loader accepts KEY=value, export KEY=value, quoted values, and comments, but does not execute
shell commands.
It does not install hooks, native agent profiles, a global AGENTS.md, or change the selected root
model. All four skills contain routing instructions only and reuse the same MCP runtime.
Restart the ChatGPT desktop app, reload the VS Code Codex extension, and start a new Codex CLI session after installation. The MCP registration is shared by all three local Codex clients.
Verify agent_trio with /mcp in the ChatGPT desktop app or Codex CLI, or with MCP servers in
the VS Code Codex extension. Then choose one mode:
# ChatGPT desktop app in Codex, VS Code Codex, or interactive Codex CLI
# One turn only; later turns must mention it again.
$agent-trio implement this feature and run the relevant tests
# Related follow-ups in this conversation continue through Agent Trio automatically.
$agent-trio-session implement this feature and run the relevant tests
# Quality-first variants always delegate and retain the wider V3.3 DAG policy.
$agent-trio-quality analyze this repository and report correctness risks
$agent-trio-quality-session build this feature and handle my related follow-upsFor a non-interactive CLI run, keep the $ inside single quotes:
codex exec '$agent-trio research these alternatives and produce a comparison'ChatGPT Chat and Work use @ instead of Codex $ mentions. The non-session skills apply to one
turn. After either session skill is explicitly selected once, related corrections, refinements,
continuations, and questions retain that profile. Say to stop using Agent Trio, ask for normal
Codex, switch to an unrelated task, or start a new conversation to leave session mode.
For foreground invocations, the selected skill passes flat top-level MCP arguments, supplies a
unique run ID, submits the run for immediate durable acceptance, and then waits once for its final
result only after submit succeeds with that same ID. ChatGPT and Codex clients
with MCP Apps support therefore mount the live Monitor near the start of execution instead of after
the run finishes; no separate browser tab is required. Select any planner, leaf, direct agent,
integrator, or final-review thread to inspect its messages, reasoning summaries, commands, file
changes, token usage, cost, and validation state. The component reads cursor-based updates by
calling status through the MCP Apps bridge. Those calls stay inside the component and never invoke
a model. Clients without MCP Apps support keep the local monitorUrl text fallback.
The public MCP contract uses canonical field names and values. In particular, direct calls use
directTier, capabilities are {kind,name,path?} objects, limits are nested under limits, and
fanout-only risk, merge, access, and tasks live under semanticPlan. The runtime also
normalizes a bounded set of unambiguous call shapes emitted by older installed skills or Codex
clients, including permission-label aliases and a split request envelope. If canonical and legacy
fields disagree, the call is rejected rather than silently changing its meaning. Reinstalling after
an upgrade refreshes the skills so new calls use only the canonical contract.
All four skills also pass the current Codex task permission and approval modes to Agent Trio. A Full
access task gives direct agents and execution leaves Full access, including network access;
Workspace access and Read-only tasks remain correspondingly restricted. Approve for me is inherited
through App Server automatic review. Neither skill may request stronger access or approval than
the calling task. Calls made without a skill can set the same context explicitly through MCP
hostAccess/hostApproval or CLI --host-access/--host-approval.
Useful installation commands:
npm run install:user -- --job-root /absolute/job/path
npm run install:user -- --price-table /absolute/prices.json
npm run uninstall:userExecution Model
request
|
v
host Sol balanced semantic route
|-- tiny/indivisible ----------> root completion (no MCP)
|-- one proven work unit ------> one Luna/Terra execution agent
|
`-- 2-3 useful work units -----> host semanticPlan
|
v
deterministic DAG scheduler
|-- Luna leaves
|-- Terra leaves
`-- at most one Sol specialist
|
v
local reduction or Terra integration
|
`-- anomaly-only lazy Sol PlanPatch
quality skill
`-- always delegate: one agent or a 2-5-leaf DAG
CLI / insufficient host context
|
`-- deterministic bounded direct, otherwise one adaptive Sol plan
|-- 1 leaf --> planned single agent
`-- 2-5 leaves --> DAG schedulerThe current root Sol decides root completion versus delegation, direct versus fanout, domain, semantic boundaries, dependencies, model floors, and integration requirements. Balanced fanout requires two independent leaves over 30 seconds and at least 90 seconds of serial work; it defaults to two leaves and uses three only for three substantial streams when that lowers the predicted critical path by at least 20% versus the best two-leaf grouping. Quality retains the 15-second and two-to-five-leaf V3.3 policy. Code handles permissions, launches, joins, concurrency, budgets, cancellation, recovery, and message delivery without rewriting those semantic choices.
Balanced delegates one worker only when at least three matching historical samples predict at most
40% of direct Sol cost and 100% of its latency; otherwise the host Sol keeps the work. For fanout,
matching history applies hard 40% cost and 70% latency admission. A cold start also needs distinct
structural work units and must pass conservative 30% cost and 55% latency limits. Missing prices,
history, or structural evidence cannot prove fanout value, so an already submitted runtime request
falls back to one cheapest sufficient worker. Quality is exempt from these economic vetoes unless
the caller sets maxCostUsd.
A CLI or non-Sol caller uses auto: the runtime takes a zero-model direct route only for a provably
bounded single objective; otherwise one internal Sol turn chooses a single execution agent or a
bounded DAG.
Model Routing
Tier | Primary responsibility |
Luna | Search, extraction, data processing, focused implementation, tests, read-only preparation |
Terra | Recovery/stateful work, coupled debugging, semantic merge, final office writer |
Sol | Planning, difficult algorithms, architecture, security, hidden correctness risks |
Bounded work defaults to Luna. A Balanced DAG has at most one Terra execution node, counting a Terra
writer or Terra integration; office, review, recovery, or synthesis words do not raise unrelated
leaves. A leaf is promoted only when its own evidence shows that stronger reasoning is needed, and
successful sibling work is retained. A normal host plan starts no internal Sol thread. A blocker,
material conflict, contract change, non-mechanical validation failure, or low confidence can lazily
start one internal Sol continuation for a minimal PlanPatch.
Scheduler
Profile defaults:
Limit | Balanced foreground | Balanced durable | Quality foreground | Quality durable |
Concurrent leaves | 3 | 3 | 5 | 5 |
Total leaves | 3 | 5 | 8 | 20 |
Dependency waves | 3 | 3 | 3 | 3 |
Sol specialist leaves | 1 | 1 | 1 | 1 |
Sol replans | 1 | 1 | 1 | 1 |
Balanced is intentionally capped at three foreground leaves. Quality durable auto-research may use up to 20 total leaves while retaining the five-way concurrency and three-wave ceiling.
Independent writers in a clean Git repository receive isolated temporary worktrees. Their patches are ownership-checked, combined, validated, and then applied to the original workspace. Read-only leaves share the request workspace. Dirty and non-Git workspaces use a single writer.
The default model map is:
luna -> gpt-5.6-luna
terra -> gpt-5.6-terra
sol -> gpt-5.6-solCLI
The CLI and Desktop MCP tool use the same runtime core.
For direct CLI use, declare the permission and approval modes of the environment launching the task:
agent-trio run --host-access full-access --host-approval never 'inspect the configured package sources'
agent-trio run --host-access workspace-write --host-approval approve-for-me 'implement the requested repository change'
agent-trio run --host-access read-only --host-approval never 'analyze this project without changing it'Omitting these flags retains the original workspace-scoped, non-approving behavior for compatibility.
agent-trio run "implement the requested feature" -C /workspace
agent-trio run --profile quality "perform a deep repository analysis" -C /workspace
agent-trio run "update the report" -C /workspace --skill documents
agent-trio run "inspect the signed-in page" -C /workspace --plugin browser@openai-bundled
agent-trio submit "build a research dossier" -C /workspace --run-id dossier-01
agent-trio status dossier-01
agent-trio resume dossier-01 --input "repository permission granted"
agent-trio cancel dossier-01
agent-trio benchmark observations.jsonUse --profile balanced|quality to select the default policy; balanced is the default. An explicit
--strategy auto|direct|fanout takes precedence over profile routing. In auto, clearly bounded
single-agent work stays on the deterministic direct path, while other work receives one adaptive
internal Sol plan.
The CLI prints the local Monitor URL before a foreground model run starts and includes it in
submitted and status results. MCP Apps clients use the embedded view; clients that only support
progress notifications receive the local URL as a fallback. Final structured results retain
monitorUrl for compatibility.
MCP Tool
The local Codex clients expose one MCP tool named agent_trio with five actions:
Action | Purpose |
| Execute a foreground request |
| Start a durable background request |
| Read the latest persisted state |
| Continue the original App Server thread with supplied input |
| Interrupt an active run without replaying completed side effects |
All installed skills implement this foreground flow when they call the runtime:
generate unique runId -> submit(runId, monitorFirst=true)
-> on successful response with the same runId: status(runId, wait=true) once
-> on MCP/tool error: stop without statusTool arguments are flat fields such as action, runId, objective, and cwd; callers must not
nest the whole argument object beneath request, input, or arguments. The runtime accepts one
legacy request wrapper for compatibility, but the public schema and documented format remain
flat. risk and merge belong inside semanticPlan only when strategy=fanout; direct requests
omit the plan and all plan-only fields. For compatibility, the runtime discards valid misplaced
top-level hints on direct/auto requests and moves non-conflicting hints into a fanout plan.
The first call returns as soon as the foreground run has a durable snapshot, which gives the host a
completed tool result to attach the component to. The second call waits on that same run locally;
it does not start another planner, leaf, reviewer, or model turn. The component performs its own
cursor-based status long polling over the MCP Apps bridge, and those component calls never enter
the model context. Ordinary durable background submissions omit monitorFirst and return after
acceptance without the one-time foreground wait.
Child App Server threads have project instruction loading, native multi-agent orchestration, and recursive Agent Trio access disabled.
Configuration
Variable | Purpose |
| Durable snapshot and event directory |
| Override model price table |
| App Server provider override |
| Shared service tier |
| Path to the pinned Codex executable |
| Child home: |
| Luna model override |
| Terra model override |
| Sol model override |
| Enable explicitly selected plugin capabilities |
| Planner: |
| Responses-compatible planner endpoint |
| Planner bearer credential |
| Planner model override |
| Planner-only service tier |
| Disable local Monitor capture and URLs |
| Fixed loopback Monitor port override |
The bundled standard-context price table is
config/openai-prices.standard.json. Custom model names or
providers require an explicit price table so admission and hard cost limits can be calculated before
execution.
The planner transport defaults to auto: it uses a Responses-compatible provider when configured
and falls back to Codex App Server. Responses planning is tool-free and uses strict structured
output.
Monitor
The primary Monitor is a self-contained MCP Apps resource attached to the existing agent_trio
tool. It renders inside compatible ChatGPT and Codex clients and calls the same tool with private
cursor and revision fields for bounded long polling. The local loopback web UI remains available to
the CLI and clients without MCP Apps support. Neither presentation starts agents, reviews results,
or participates in scheduling.
App Server completed items and lifecycle notifications are written to a separate bounded
monitor.jsonl stream, while job.json remains authoritative. Token delta notifications are not
stored. The recorder uses a 512 KiB pending-memory ceiling, a 16 KiB per-event ceiling, and an 8 MiB
per-run log ceiling. Both views render one conversation entry per completed message, reasoning item,
tool call, command, or file change, retain bounded UI state, and add no model calls or tokens. The
loopback fallback still listens only on 127.0.0.1 and uses a private per-job-root token.
Development
npm run check keeps the authored Office corpus disabled because generating and qualifying that
release benchmark is intentionally resource intensive. Run it explicitly on a machine with
LibreOffice using:
AGENT_TRIO_RUN_AUTHORED_CORE_TESTS=1 npm test -- tests/authored-core-benchmark-corpus.test.tsnpm run format:check
npm run lint
npm run typecheck
npm test
npm run build
npm run doctor -- --project-onlyThe normal test configuration uses one Vitest worker to keep App Server fixture memory bounded.
Documentation
Available Tools
24 toolsartifact_getRead artifactA
Read a bounded prefix of an artifact by ID. Prefer targeted retrieval over loading full artifacts.
Inputs: artifactId (required), encoding, maxBytes.
artifact_putStore artifactA
Store bounded content in the content-addressed artifact store. Required fields are taskId, actorId, kind, mimeType, content, encoding, and idempotencyKey. Do not send missionId. Return artifact references instead of copying large content into agent messages.
Inputs: kind (required), taskId (required), actorId (required), content (required), +4 more.
budget_reportReport resource usageA
Atomically add token, cost, wall-time, and tool-call usage to a mission and optionally a task. Hard limits are enforced.
Inputs: usage (required), actorId (required), missionId (required), idempotencyKey (required), +3 more.
children_statusList compact child statusA
Read direct children of a coordinator task as compact status rows (ids, status, version, summary, leaseExpired). Call once after wait_agent. Do not poll with task_get. If leaseExpired, cancel instead of waiting again.
Inputs: parentTaskId (required).
mission_closeClose missionA
Complete a mission only after every task is terminal. Failed tasks require an explicit acceptance decision.
Inputs: actorId (required), missionId (required), idempotencyKey (required), expectedVersion (required), +1 more.
mission_createCreate missionA
Create the durable mission record before spawning agents. strategy is locked at create (default fanout). directorPlan is required only for director_plan: a workspace-relative .md path to the plan file Sol wrote in the project folder. Forbidden otherwise.
Inputs: risk (required), actorId (required), objective (required), idempotencyKey (required), +6 more.
mission_getGet missionA
Read a mission and optionally its task, artifact, claim, and review state. Treat this result as authoritative over chat summaries. The mission row includes strategy, portrait, and directorPlan (workspace-relative plan file path) even when includeDetails is false.
Inputs: missionId (required), includeDetails.
recovery_snapshotGet recovery snapshotA
Read durable mission state and a bounded audit-event page after interruption, compaction, or client restart.
Inputs: missionId (required), eventLimit, afterSequence.
result_checkCheck candidate resultA
Independently check a candidate. The reviewer cannot be the producer. Luna verifiers call this on review_target_task_id without claiming. Rejection returns the task to ready.
Inputs: notes (required), taskId (required), approved (required), reviewerId (required), +3 more.
results_gate_and_commitGate and commit low-risk childrenA
For low or medium risk only, record check and verify reviews then commit in one call. Does not skip gates. High or critical work must use luna-verifier plus result_check, result_verify, and task_commit. Children must already be candidate. On a direct mission, Sol (not the Luna producer) may be the reviewer without parentTaskId.
Inputs: decisions (required), reviewerId (required), idempotencyKey (required), parentTaskId.
result_submit_candidateSubmit candidate resultA
Submit a worker result as candidate only. This closes the producer lease; a different reviewer must check it. artifactRefs must belong to this taskId — call artifact_put on the same task first, and do not attach child-task artifacts. Include actual usage when known. summary max 500 characters.
Inputs: claims (required), taskId (required), summary (required), workerId (required), +6 more.
result_verifyVerify checked resultC
Apply the second evidence gate to a checked result. Approval produces verified, not committed.
Inputs: notes (required), taskId (required), approved (required), reviewerId (required), +3 more.
task_allocateAllocate taskB
Allocate a policy-checked work package before native spawn_agent. Put the returned task_id into the child's prompt. Root role depends on mission.strategy: fanout/director_plan/pipeline require Terra; direct allows one root Luna. fanout Terra objective max 2000 characters.
Inputs: risk (required), role (required), model (required), actorId (required), +15 more.
task_blockBlock taskC
Record a blocking dependency while retaining the lease. Continue heartbeats or release the task.
Inputs: reason (required), taskId (required), workerId (required), leaseToken (required), +2 more.
task_cancelCancel taskA
Cancel a non-terminal task after its direct children are terminal. Child cancellation requires the running direct parent's version and lease token.
Inputs: reason (required), taskId (required), actorId (required), idempotencyKey (required), +3 more.
task_claimClaim taskB
Atomically claim a ready task using optimistic versioning. The returned lease token is required for worker mutations.
Inputs: taskId (required), workerId (required), idempotencyKey (required), expectedVersion (required), +1 more.
task_commitCommit verified taskB
Commit a verified task after every direct child is terminal. This may unlock dependent tasks.
Inputs: taskId (required), actorId (required), idempotencyKey (required), expectedVersion (required).
task_failFail taskA
Record a definitive worker failure, clear its lease, and charge final usage. Future sibling allocation counts actual failed usage instead of the full reservation.
Inputs: reason (required), taskId (required), workerId (required), leaseToken (required), +3 more.
task_getGet taskC
Read the authoritative task version, lease, assignment, inputs, budget, and status before mutating it.
Inputs: taskId (required).
task_heartbeatRenew task leaseA
Renew an active lease. Use this during long tool calls; an expired lease may be reclaimed by another worker.
Inputs: taskId (required), workerId (required), leaseToken (required), idempotencyKey (required), +2 more.
task_releaseRelease taskA
Return a leased/running/blocked task to ready when the current worker cannot continue. Include a concrete reason.
Inputs: reason (required), taskId (required), workerId (required), leaseToken (required), +2 more.
task_set_effortSet task reasoning effortA
Change model reasoning effort while a task is ready and unleased, within its recorded maximum. Child changes require direct-parent authority.
Inputs: reason (required), taskId (required), actorId (required), idempotencyKey (required), +4 more.
task_startStart taskC
Move a leased task to running and establish its result producer.
Inputs: taskId (required), workerId (required), leaseToken (required), idempotencyKey (required), +1 more.
task_supersedeSupersede failed taskB
Link a failed task to a viable sibling replacement for audit and closure. Child supersession requires direct-parent authority.
Inputs: reason (required), taskId (required), actorId (required), idempotencyKey (required), +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
The tools are grouped by resource (mission/task/artifact/result) and most have clear roles, but several lifecycle transitions overlap: task_release, task_fail, task_cancel, and task_supersede all end or abandon work in subtly different ways, and result_check, result_verify, and results_gate_and_commit represent closely related review stages. Descriptions help, but an agent could still misselect the wrong transition for a given task state.
The dominant verb_noun pattern (task_claim, task_start, mission_create, artifact_put) is consistent and predictable across the set. Minor exceptions like recovery_snapshot, children_status, and results_gate_and_commit break the pattern slightly but remain readable and understandable.
24 tools is at the high end and feels heavy, even for a hierarchical orchestration server. The count is justified by the broad lifecycle, but several review/commit and task-failure tools could plausibly be consolidated to reduce selection overhead.
The tool set covers the full mission/task lifecycle, artifact storage, result verification gates, budget accounting, cancellation, failure handling, supersession, and recovery. Minor gaps remain, such as no general mission/task listing or dedicated result retrieval endpoint, but the core workflow has no obvious dead ends.
Maintenance
Related MCP Connectors
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Governed MCP: agent audit, provenance, deterministic checks, and receipt-backed FragGate execution.
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Related MCP Servers
- AlicenseBqualityBmaintenanceGoverned agent execution gateway for LLM workflows, providing deterministic FSM-based execution, audit trails, and idempotency guarantees via MCP.6MIT
- FlicenseNot gradedqualityCmaintenanceDurable MCP control plane for coordinating agent networks, with message ledger, idempotent delivery, and cryptographic identity for each orchestrator.-
- AlicenseNot gradedqualityFmaintenanceA durable MCP control plane for starting, observing, steering, continuing, cancelling, and handing off long-running coding agents, with bounded MCP calls and persistent worktrees.14 npmMIT
- AlicenseAqualityBmaintenanceRetired snapshot of the former 15-tool Apache-2.0 beta. Use Living Stack Community for the free seven-tool proof edition; Complete Local is the paid runtime with memory, recovery, signed traces, release verification, and multi-agent workflows.14Apache 2.0