Skip to main content
Glama
hierarchical-codex

hierarchical-codex

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:user

install: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-session under ~/.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-ups

For 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:user

Execution 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 scheduler

The 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-sol

CLI

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.json

Use --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

run

Execute a foreground request

submit

Start a durable background request

status

Read the latest persisted state

resume

Continue the original App Server thread with supplied input

cancel

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 status

Tool 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

AGENT_TRIO_JOB_ROOT

Durable snapshot and event directory

AGENT_TRIO_PRICE_TABLE

Override model price table

AGENT_TRIO_MODEL_PROVIDER

App Server provider override

AGENT_TRIO_SERVICE_TIER

Shared service tier

AGENT_TRIO_CODEX_PATH

Path to the pinned Codex executable

AGENT_TRIO_CODEX_HOME_MODE

Child home: projected, temporary, or inherit

AGENT_TRIO_LUNA_MODEL

Luna model override

AGENT_TRIO_TERRA_MODEL

Terra model override

AGENT_TRIO_SOL_MODEL

Sol model override

AGENT_TRIO_ALLOW_PLUGINS=1

Enable explicitly selected plugin capabilities

AGENT_TRIO_PLANNER_TRANSPORT

Planner: auto, responses, or app-server

AGENT_TRIO_PLANNER_BASE_URL

Responses-compatible planner endpoint

AGENT_TRIO_PLANNER_API_KEY

Planner bearer credential

AGENT_TRIO_PLANNER_MODEL

Planner model override

AGENT_TRIO_PLANNER_SERVICE_TIER

Planner-only service tier

AGENT_TRIO_MONITOR=0

Disable local Monitor capture and URLs

AGENT_TRIO_MONITOR_PORT

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.ts
npm run format:check
npm run lint
npm run typecheck
npm test
npm run build
npm run doctor -- --project-only

The normal test configuration uses one Vitest worker to keep App Server fixture memory bounded.

Documentation

Available Tools

24 tools
artifact_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

    B3.1/5.0

    Scored across 24 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      A 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 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Retired 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.
      14
      Apache 2.0