convez.ai
MCP ServerAutomaçãoAvançado
Caleb0796

Ultracode for Codex

Caleb0796/codex-ultracode

Orquestração determinística de agentes Codex em sessão via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que porta a orquestração de múltiplos agentes do Claude Code para OpenAI Codex. Implementa determinismo no paralelismo de workers via TypeScript, com suporte a padrões como pipeline, barrier e síntese de resultados. Inclui testes offline completos e verificação de contrato SDK.

Instalação

$npx convez-ai Caleb0796/codex-ultracode

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Executar múltiplos workers de Codex em paralelo com controle de concorrência
  • Implementar padrões de multi-agent como adversarial verify e judge panel
  • Orquestrar tarefas complexas com isolamento de worktree e budget de tokens
  • Fan-out determinístico de agentes mantendo contexto de rede em sessão

Veredito

Ferramenta madura e verificada para orquestração de agentes Codex com padrões sofisticados. Recomendada para equipes que precisam de multi-agent determinístico; requer familiaridade com Codex SDK e conceitos de concorrência.

README

A tradução para o português deste README ainda está na fila.

Ultracode for Codex

Bring Claude Code's Workflow tool — "ultracode", deterministic multi-agent orchestration — to OpenAI Codex. This repo holds a verified TypeScript implementation on @openai/codex-sdk (with an in-session MCP-server front door), the original Python kit, and the analysis behind both.

Status: TS port verified green — tsc + 18/18 offline tests + live preflight + live engine smoke + MCP tool fan-out end-to-end (one ultracode(n=2) call → 2 child codex workers, network retained, synthesis + ledger). See Verification.


The core idea

Claude Code's "dozens of agents" don't come from the model deciding to spawn them — they come from a deterministic harness that holds the concurrency number in code (parallel() / pipeline() loops). Codex's in-session spawn_agent is the opposite: model-driven and trained to be conservative (the docs say it "only spawns a new agent when you explicitly ask," and the canonical examples spawn 2–6). No prompt reliably gets it to dozens.

So this project holds the concurrency number in code and uses Codex as the agent primitive:

  • Engine — agent() / parallel() (barrier, all-settled → null) / pipeline() (no barrier) + an output-token budget ceiling, worktree isolation for parallel writers, structured-output schemas, and a run ledger.
  • Methodology — the patterns that make it ultracode rather than a parallel map: adversarial verify, judge panel (synthesize + graft), multi-modal sweep, loop-until-{dry,count,budget}, completeness critic, review-then-verify.
  • MCP front door (TS) — register the orchestrator as an MCP server; the in-session model calls ultracode(task, n?) as one tool, and the server (a sibling of the harness, outside the per-command sandbox, so it keeps network) deterministically fans out N workers. This is what makes deterministic fan-out an in-session primitive — source-verified against codex-rs/rmcp-client/src/stdio_server_launcher.rs.

What's here

PathWhat
ts/The TypeScript port on @openai/codex-sdk + the MCP-server front door. The latest, verified implementation. See ts/README.md.
codex_workflow.py / codex_patterns.pyThe original Python kit (driving codex exec subprocesses).
docs/parity-with-claude-ultracode.mdGap analysis vs Claude Code's ultracode — what's at parity, what's closable, what's architectural.
workflow-in-codex.mdDesign notes + the original parity write-up.
ultracode-codex-setup.mdThe in-session native-skill setup (spawn_agent / spawn_agents_on_csv).
ultracode-test-plan.mdTest plan for the native-skill kit.
review-findings.mdAdversarial review of the global AGENTS.md.

Quickstart (TypeScript)

cd ts
npm install
npm run typecheck     # tsc --noEmit
npm test              # vitest — offline suite (SDK stubbed, no network/tokens) — 18/18
npx tsx src/preflight.ts   # CodexEnv probe — run once before live use (needs codex auth + tokens)

preflight.ts round-trips the real SDK↔CLI contract (resume identity, mcp_servers={} + --output-schema, usage.output_tokens, effort override). Don't trust resume/budget until it passes.


How to use

1. The engine (TypeScript)

import * as wf from "./src/codexWorkflow.js";
import { z } from "zod";

// Fan out — barrier; a failed agent becomes null (never aborts the batch).
const Answer = z.object({ answer: z.number() });
const results = await wf.parallel([
  () => wf.agent('Compute 6*7. Return JSON {"answer": <number>}.', { schema: Answer }),
  () => wf.agent('Compute 8*9. Return JSON {"answer": <number>}.', { schema: Answer }),
]);
// results: [{answer:42}, {answer:72}]

// Pipeline — NO barrier; each item flows through all stages independently.
//   stage(prev, originalItem, index); a throwing stage drops that item to null.
const out = await wf.pipeline(files, review, verify);

// Budget — output-token ceiling (env CODEX_WF_BUDGET; unset = unlimited).
wf.budget.total; wf.budget.spent(); wf.budget.remaining();

// Worktree isolation — the agent edits files only; the orchestrator (out of sandbox) runs git,
// auto-cleans the worktree+branch, and collects the diff.
await wf.agent("Add a subtract() function to mathlib.ts", { isolation: "worktree", cwd: repo });
wf.collectedDiffs(); // [{ branch, diff }]

// Run ledger
wf.startRun("my-run"); wf.saveResult("findings", obj); wf.writeLedger({ Summary: "…" });

Schema notes: pass a Zod schema (preferred — validated client-side) or a plain JSON Schema. Caller-optional fields must be z.T().nullable() (not .optional()); the engine widens them so an OpenAI-strict schema can still let the model emit null.

2. The methodology (patterns)

import * as p from "./src/codexPatterns.js";

// N independent skeptics try to REFUTE; survives only by majority (tie = kill).
await p.adversarialVerify("divide(x,0) raises", { lenses: ["correctness", "security", "reproduce"] });

// N attempts → judge scores → synthesize from the winner WHILE grafting runner-up ideas.
await p.judgePanel("Design a cache layer", ["LRU-first", "write-through", "TTL-first"], OutSchema);

// Each agent searches a DIFFERENT way, then dedupe-union.
await p.multiModalSweep(["name", "content", "caller", "commit-history"], "the repo", { schema: Found });

// Discovery loops: stop on K dry rounds / target count / token budget.
await p.loopUntilDry(finder, key);
await p.reviewThenVerify(["bugs", "perf", "security"], FindSchema); // reviewer per dimension, each finding verified

3. The MCP front door (in-session, the gap-closer)

Build, then register in ~/.codex/config.toml (auth/PATH must be explicit — the launcher does env_clear):

cd ts && npm run build   # produces dist/mcpServer.js
[mcp_servers.ultracode]
command = "/opt/homebrew/bin/node"                       # absolute — launches regardless of curated PATH
args = ["/abs/path/to/ts/dist/mcpServer.js"]

[mcp_servers.ultracode.env]
HOME = "/Users/you"
CODEX_HOME = "/Users/you/.codex"                          # so the server + its child codex runs find auth.json
PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"

Then in any codex session, the model can call:

  • ultracode(task, n?) — fan out N read-only workers + synthesize; returns { run_id, workers, result }.
  • ultracode_review(dimensions, target?) — reviewer per dimension, each finding adversarially verified.
  • workflow_status(run_id) — read the run ledger.

Headless caveat (account-level): under non-interactive codex exec, a cloud-forced OnRequest approval auto-cancels the tool call (codex issue #24135). In an interactive codex session you approve it once and the fan-out proceeds (children run outside the sandbox, keeping network). You can also drive the tool directly with npm run mcp:call — the exact server code path, end-to-end.

4. The Python kit

import codex_workflow as wf
import codex_patterns as cp

res = wf.parallel([lambda: wf.agent("...", schema=S), lambda: wf.agent("...", schema=S)])
cp.adversarial_verify("claim", lenses=("correctness", "security"))
cp.review_then_verify(["bugs", "perf"], find_schema)

Knobs via env: CODEX_WF_CONCURRENCY, CODEX_WF_MODEL, CODEX_WF_EFFORT, CODEX_WF_CWD, CODEX_WF_BUDGET.


Environment knobs (shared, TS + Python)

EnvDefaultMeaning
CODEX_WF_MODELgpt-5.5model for agents
CODEX_WF_EFFORTmediumreasoning effort (minimal/low/medium/high/xhigh)
CODEX_WF_CONCURRENCYmin(16, cores-2)max concurrent child codex processes
CODEX_WF_CWD$PWDbase working dir / git repo for worktrees + ledger
CODEX_WF_BUDGETunset = unlimitedoutput-token ceiling (agents throw once reached)
CODEX_WF_MCP_CLEAN1run child agents MCP-clean (mcp_servers={})
CODEX_WF_ARGS—JSON value exposed to the script as args

Gap vs Claude Code's ultracode

Full analysis in docs/parity-with-claude-ultracode.md. Summary:

CapabilityStatusNote
agent / parallel / pipeline semantics, schema output, concurrency capat parity+ a 1000-agent lifetime cap and 4096-item batch cap
Quality patterns (verify / judge / sweep / loops / critic / review)at parityfull methodology ported (TS + Python)
In-session deterministic fan-out that keeps networkclosablevia the MCP-server front door (source-verified)
Structured token usageat parity / betterfrom the SDK's turn.usage, not footer-scraping
ResumepartialresumeThread + a read-only content-hash cache (not full cached-prefix replay)
Live background progress treepartialrunStreamed data + ledger; no in-client /workflows tree
Writers run tests in-agentblocked / spikeaccount cloud OnRequest forbids exec-mode shell; verification is orchestrator-side
Per-agent model / effort overrideCodex advantagericher than a fixed agentType registry

Status & verification

The TypeScript port is verified green (2026-06-16): npm install · tsc --noEmit · 18/18 offline vitest · live preflight 4/4 · live engine smoke (parallel agents + worktree writer, no leak) · MCP stdio handshake · MCP tool fan-out end-to-end (one ultracode(n=2) call → 2 child codex workers that retained network → synthesis + ledger). The Python kit is the earlier, separately-verified reference.

Re-run any of it:

cd ts
npm test            # offline (no tokens)
npm run live        # live engine smoke (needs codex auth + tokens)
npm run mcp:call    # ultracode MCP tool, end-to-end (needs codex auth + tokens)
Ver o original no GitHub

Bom para

Relacionados