### Setup Development Environment

Source: https://github.com/yuanpingsong/ultracodex/blob/main/CONTRIBUTING.md

Install dependencies and run the full test suite to verify the environment.

```bash
pnpm install
pnpm typecheck && pnpm build && pnpm test
```

--------------------------------

### Install and Initialize ultracodex

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/announcement-drafts-v0.5.0.md

Commands to install the CLI globally and perform initial environment setup.

```bash
npm install -g ultracodex
ultracodex doctor
ultracodex sync-skills
```

--------------------------------

### Install UltraCodex from Source

Source: https://github.com/yuanpingsong/ultracodex/blob/main/README.md

Commands to clone the repository and install dependencies globally.

```bash
git clone https://github.com/YuanpingSong/ultracodex && cd ultracodex
pnpm install && pnpm build && pnpm link --global
```

--------------------------------

### AppServerClient.start

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/module_api.md

Initializes and starts the application server process.

```APIDOC
## AppServerClient.start

### Description
Spawns the application server process, performs the initialization handshake, and returns a client instance.

### Parameters
- **opts** (AppServerClientOptions) - Required - Configuration object containing binary path, working directory, and environment variables.
```

--------------------------------

### Run the hello workflow

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/hello/README.md

Execute the hello example workflow using the Ultracodex CLI with watch mode enabled.

```bash
ultracodex run examples/hello/workflow.js --watch
```

--------------------------------

### Global Install for Opencode

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/skills.md

Copies skills to the global opencode configuration directory for system-wide access.

```bash
mkdir -p ~/.config/opencode/skills && cp -r "$(npm root -g)/ultracodex/skills/." ~/.config/opencode/skills/
```

--------------------------------

### Install as Claude Plugin

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/skills.md

Adds the ultracodex repository as a plugin to the Claude environment.

```bash
claude plugin marketplace add YuanpingSong/ultracodex
claude plugin install ultracodex@ultracodex
```

--------------------------------

### Configure Routing and Backends in config.toml

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/operations.md

Example configuration for routing specific tasks to different backends and defining backend-specific parameters.

```toml
[route]
"impl:*"     = "opencode" # mixed routing: implementation on one vendor…
"critique:*" = "claude"   # …judgment on another. ADVANCED: usually unneeded —
                          # results return to your Claude session, which verifies free
"*"          = "codex"    # everything else goes to Codex

[backends.codex]
sandbox        = "workspace-write"
default_model  = "gpt-5.5"
default_effort = "xhigh"
service_tier   = "standard"    # never inherit fast mode from ~/.codex
model_map      = { opus = "gpt-5.5", sonnet = "gpt-5.4", haiku = "gpt-5.4-mini" }

[backends.opencode]
model       = "deepseek/deepseek-chat"  # "provider/model" as your opencode names them
binary      = "opencode"                # override for a pinned install
model_map   = { sonnet = "deepseek/deepseek-chat" }   # script tier → provider/model
variant_map = { high = "high" }         # script effort → provider variant (omit = none)

[run]
concurrency = 6                # default: min(16, cores-2)
```

--------------------------------

### Configure Scheduled Task Budgets

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/schedule.md

Examples of applying token budgets to scheduled commands to ensure quota safety.

```sh
ultracodex schedule add digest --every 30m --budget 200k -- run digest.js
```

```sh
ultracodex schedule add digest --every 30m -- run digest.js --budget 200k
```

--------------------------------

### Sync Skills for Claude Code

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/skills.md

Installs all static skills into the current project's .claude/skills/ directory.

```bash
ultracodex sync-skills
```

--------------------------------

### Update and Verify Ultracodex Installation

Source: https://github.com/yuanpingsong/ultracodex/blob/main/CHANGELOG.md

Use this command to update the global installation of Ultracodex and run the doctor utility to verify the environment.

```bash
npm install -g ultracodex && ultracodex doctor
```

--------------------------------

### GET /event

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/research/opencode-probe.md

Subscribes to server-sent events (SSE) for session activity and usage updates.

```APIDOC
## GET /event

### Description
Establishes an SSE connection to receive real-time updates including server status, message deltas, and usage ticks.

### Method
GET

### Endpoint
/event
```

--------------------------------

### Fault specification example

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/org.md

Example of quoting an ID containing special characters within a fault specification.

```bash
late:"pkg:@scope/name:1.2.3":2
```

--------------------------------

### Agent Script Skeleton

Source: https://github.com/yuanpingsong/ultracodex/blob/main/skills/agent-script-authoring/SKILL.md

A complete example of an Agent Script structure, including the required meta export, schema definition, phase declaration, and parallel agent execution.

```javascript
export const meta = {
  name: 'find-flaky-tests',
  description: 'Find flaky tests and propose fixes',
  phases: [
    { title: 'Scan', detail: 'grep test logs for retries' },
    { title: 'Fix', detail: 'one agent per flaky test' },
  ],
}

const FLAKY_SCHEMA = {
  type: 'object',
  properties: { tests: { type: 'array', items: { type: 'string' } } },
  required: ['tests'],
  additionalProperties: false,
}

phase('Scan')
const scan = await agent('Grep the CI logs under ./logs for retry markers; return every flaky test name.', { schema: FLAKY_SCHEMA })
if (!scan) return { error: 'scan agent failed' }

phase('Fix')
const fixes = (await parallel(scan.tests.map((t) => ()
  agent(
    `Diagnose why test "${t}" is flaky and fix it. Run the test 5x to confirm stability.`,
    { label: `fix:${t}` },
  ),      // <- closes agent(
)))       // <- closes map(, then parallel(, then the (await ...) wrapper
  .filter(Boolean)

log(`${fixes.length}/${scan.tests.length} tests fixed`)
return { fixed: fixes.length, of: scan.tests.length }
```

--------------------------------

### Overdue schedule warning message

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/schedule.md

Example of the warning message printed to stderr when a schedule exceeds 1.5x its expected interval.

```text
schedule 'digest' looks overdue (expected ~2026-01-01T12:30:00.000Z) — is cron running?
```

--------------------------------

### Execute Release Command

Source: https://github.com/yuanpingsong/ultracodex/blob/main/CONTRIBUTING.md

Perform the full release sequence including versioning, tagging, and publishing.

```bash
pnpm release <patch|minor|major>
```

--------------------------------

### Run pilot-then-full workflow

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/pilot-then-full/README.md

Executes the workflow script with specific database and table arguments. Ensure the database path and table name are updated to point to your local data.

```bash
ultracodex run examples/pilot-then-full/workflow.js --watch \
  --args '{"db":"/path/to/collection.db","table":"records"}'
```

--------------------------------

### Initialize and Tick Org

Source: https://github.com/yuanpingsong/ultracodex/blob/main/README.md

Commands to scaffold an agent tree and trigger agent execution cycles.

```bash
ultracodex org init      # scaffold the agent tree from coverage.toml
ultracodex org tick      # wake whoever is due, deliver messages, lint
```

--------------------------------

### Run Release Checks

Source: https://github.com/yuanpingsong/ultracodex/blob/main/CONTRIBUTING.md

Execute the full hermetic suite and demo-video tasks to ensure release readiness.

```bash
pnpm release:check
```

--------------------------------

### Execute Build Experiment

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/research/cmp-build/README.md

Run the cmp-build.js script within a temporary directory using the ultracodex runtime and specified budget.

```bash
mkdir -p /tmp/cmp-a/.ultracodex && cd /tmp/cmp-a
# write .ultracodex/config.toml with the route line of your choice
/usr/bin/time -p ultracodex run <this-folder>/cmp-build.js --json --budget 400k
```

--------------------------------

### Execute Workflow from CLI

Source: https://github.com/yuanpingsong/ultracodex/blob/main/README.md

Run a packaged workflow with specific task criteria and token budget.

```bash
ultracodex run goal --budget 200k --args '{"task":"Write a limerick about cron jobs.","criteria":"5 lines, AABBA, mentions crontab, actually funny."}'
```

--------------------------------

### Execute Fan-out Synthesis Workflow

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/fanout-synthesize/README.md

Run the synthesis workflow using the UltraCodex CLI with watch mode enabled.

```bash
ultracodex run examples/fanout-synthesize/workflow.js --watch
```

--------------------------------

### Run the review-verify-fix workflow

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/review-verify-fix/README.md

Executes the workflow against a target directory with optional watch mode, budget constraints, and custom arguments.

```bash
ultracodex run examples/review-verify-fix/workflow.js [--watch] [--budget 2m] [--args '{"root":"/abs/path/to/repo","checks":"pnpm typecheck && pnpm test && pnpm build"}']
```

--------------------------------

### assemblePrompt

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/module_api.md

Assembles a structured prompt for LLM execution including task, schema contracts, and profile preambles.

```APIDOC
## assemblePrompt(args: { prompt: string; schema?: Record<string, unknown>; profilePreamble?: string }): string

### Description
Constructs an XML-formatted prompt string incorporating the task, optional schema-based output contracts, and profile preambles.

### Parameters
- **args** (Object) - Required
	- **prompt** (string) - Required - The core task description.
	- **schema** (Record<string, unknown>) - Optional - The schema to enforce in the output.
	- **profilePreamble** (string) - Optional - A paragraph to prepend to the prompt.
```

--------------------------------

### UltraCodex CLI Commands

Source: https://github.com/yuanpingsong/ultracodex/blob/main/README.md

List of available commands for managing runs, schedules, and organizational runtime.

```text
ultracodex                        TUI home: Runs | Loops | Schedules | Org
ultracodex run <script|name>      [--args JSON] [--budget 500k] [--watch|--json|--detach] [--strict]
ultracodex ls | show <ref> | attach <ref>       inspect runs (ref = unique runId prefix)
ultracodex pause|resume|skip|kill <ref>         live controls
ultracodex logs <ref> [n]         raw runner / per-agent event logs
ultracodex validate <script>      dual-runnability lint (--strict = portable subset)
ultracodex schedule add|ls|pause|resume|rm      recurring runs via owned crontab lines
ultracodex org init|tick|status|send|ask|audit|replay|lint   the org runtime (experimental)
ultracodex sync-skills            static + per-workflow skills → .claude/skills/
ultracodex doctor                 env, auth, execution profile, schedules, interactive-config divergences
```

--------------------------------

### Execute Goal Workflow via CLI

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/loops.md

Run the goal workflow using the command line interface with task, criteria, and context arguments.

```bash
ultracodex run goal --args '{"task":"Implement the CSV import UI","criteria":"Build passes. Vitest passes. Users can upload a CSV and see row-level validation errors.","context":"Relevant files: src/import/, tests/import.test.ts"}' --budget 250k --json
```

--------------------------------

### Execute Staged Build Gates Workflow

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/staged-build-gates/README.md

Run the workflow using the ultracodex CLI with required project directory arguments and optional flags.

```bash
ultracodex run examples/staged-build-gates/workflow.js --args '{"projectDir": "/abs/path/to/project"}' [--watch] [--budget ...]
```

--------------------------------

### Invoke an agent with a schema

Source: https://github.com/yuanpingsong/ultracodex/blob/main/README.md

Demonstrates the basic syntax for calling an agent as a function to receive a structured result.

```javascript
await agent(prompt, { schema })
```

--------------------------------

### Configure Sandbox and Network Access in config.toml

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/operations.md

Define network access and sandbox levels within the .ultracodex/config.toml file to escalate agent permissions.

```toml
[backends.codex]
network_access = true            # 1. egress inside the sandbox (pnpm install,
                                 #    APIs, web) — file WRITES stay confined

# sandbox = "danger-full-access" # 2. no sandbox at all: writes anywhere your
                                 #    user can, network on

[profiles.Networked]             # 3. per-agent: only agents the script marks
network_access = true            #    with agentType escalate
```

--------------------------------

### Execute an UltraCodex script

Source: https://github.com/yuanpingsong/ultracodex/blob/main/skills/ultracodex/SKILL.md

Run a script file or name using the CLI, optionally specifying a token budget and input arguments.

```bash
ultracodex run <file-or-name> --json [--budget 500k] [--args '<json>']
```

--------------------------------

### Execute the actor-critic workflow

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/actor-critic-loop/README.md

Runs the predefined haiku generation task with monitoring and token limits enabled.

```bash
ultracodex run examples/actor-critic-loop/workflow.js --watch --budget 200k
```

--------------------------------

### Execute ultracodex CLI commands

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/operations.md

A collection of common commands for managing workflows, agent runs, and organizational tasks.

```bash
ultracodex                       # TUI home: saved workflows + recent runs
ultracodex run wf.js --args '{"q":"..."}' --budget 500k
ultracodex run <saved-name> --json          # machine path (what Claude calls)
ultracodex ls                               # runs with pid-liveness
ultracodex show uc_ab --wait --timeout-ms 600000
ultracodex attach uc_ab                     # TUI onto a live run
ultracodex pause uc_ab | resume uc_ab       # soft pause (stops new launches)
ultracodex skip uc_ab 4                     # resolve agent 4 to null
ultracodex kill uc_ab                       # control-stop → SIGTERM → SIGKILL
ultracodex logs uc_ab 4                     # raw codex events for agent 4
ultracodex validate wf.js --strict          # dual-runnability lint
ultracodex sync-skills                      # static skills + workflows/ → .claude/skills/*
ultracodex schedule add digest --every 30m -- run digest.js
ultracodex schedule ls                      # schedules for this project
ultracodex schedule pause digest            # pause | resume | rm <name>
ultracodex org init                         # scaffold an org from coverage.toml
ultracodex org tick                         # run due org wakes
ultracodex org audit --sample 25 --json     # audit sampled BRIEF/THESIS claims
ultracodex org replay --from 2026-07-01 --to 2026-07-07
```

--------------------------------

### Run Design Exploration Workflow

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/design-exploration/README.md

Executes the design exploration script with optional watch mode, budget constraints, and custom brief arguments.

```bash
ultracodex run examples/design-exploration/workflow.js [--watch] [--budget 500k] [--args '{"brief":"..."}']
```

--------------------------------

### runTui(opts)

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/module_api.md

Initializes and runs the terminal user interface. Resolves when the user quits the interface.

```APIDOC
## runTui(opts)

### Description
Starts the TUI. If `runDir` is provided, it attaches to that specific run; otherwise, it launches the home view.

### Parameters
- **opts** (object) - Required
  - **projectDir** (string) - Required - The root directory of the project.
  - **runDir** (string) - Optional - The directory of the specific run to view.
```

--------------------------------

### Replay command syntax

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/org.md

Command structure for re-living the ingest ledger through the tick scheduler.

```bash
ultracodex org replay [--root DIR] [--from YYYY-MM-DD] [--to YYYY-MM-DD] \
  [--faults "drop:ID;dup:ID;late:ID:DAYS"] [--pristine] [--json]
```

--------------------------------

### POST /session

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/research/opencode-probe.md

Creates a new session. The session inherits the current working directory of the server process.

```APIDOC
## POST /session

### Description
Creates a new session and returns the session ID and directory information.

### Method
POST

### Endpoint
/session

### Request Body
- **{}** (object) - Required - Empty object
```

--------------------------------

### Ultracodex Schedule CLI Commands

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/schedule.md

Standard syntax for managing task schedules via the Ultracodex CLI.

```bash
ultracodex schedule add <name> (--every <dur> | --daily <HH:MM> | --cron "<expr>") [--until-done] [--max-runs <n>] [--budget <spec>] -- <command...>
ultracodex schedule ls [--json]
ultracodex schedule pause <name>
ultracodex schedule resume <name>
ultracodex schedule rm <name>
```

--------------------------------

### Configure Backend Routing

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/research/cmp-build/README.md

Define the backend model for the ultracodex runtime by setting the route in the configuration file.

```toml
"*" = "codex"    # run A
"*" = "claude"   # run B
```

--------------------------------

### agent(prompt, opts?)

Source: https://github.com/yuanpingsong/ultracodex/blob/main/skills/agent-script-authoring/SKILL.md

Spawns an agent to process a prompt. Resolves to the agent's text response or a validated object if a schema is provided.

```APIDOC
## agent(prompt, opts?)

### Description
Spawns one agent. Without a schema, it resolves the agent's final message text; with a schema (a JSON Schema object), it resolves a validated object.

### Parameters
- **prompt** (string) - Required - The prompt to send to the agent.
- **opts** (object) - Optional - Configuration options:
  - **label** (string) - Display name for the agent.
  - **phase** (string) - Assigns the call to a progress group.
  - **model** (string) - Capability tier (e.g., 'sonnet', 'opus', 'haiku', 'fable').
  - **effort** (string) - Effort level ('low', 'medium', 'high', 'xhigh', 'max').
  - **isolation** (string) - Set to 'worktree' for a fresh git worktree per agent.
  - **agentType** (string) - Engine-defined agent profile.

### Response
- **Promise<string | object | null>** - Resolves to the agent's output or null.
```

--------------------------------

### ultracodex run

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/product_context.md

Executes a script or named task with optional configuration for budget, concurrency, and output format.

```APIDOC
## ultracodex run

### Description
Executes a specified script or task. Supports detached execution, budget constraints, and JSON output for programmatic integration.

### Usage
`ultracodex run <script.js|name> [--args '<json>'] [--budget 500k] [--watch] [--detach] [--strict] [--json] [--concurrency N]`

### Options
- **--args** (json) - Optional - Arguments passed to the script.
- **--budget** (string) - Optional - Resource budget (e.g., 500k).
- **--watch** (flag) - Optional - Enables line-per-event output.
- **--detach** (flag) - Optional - Runs the process in the background.
- **--strict** (flag) - Optional - Enables strict mode.
- **--json** (flag) - Optional - Suppresses decoration and outputs final result as JSON.
- **--concurrency** (number) - Optional - Sets the concurrency level.
```

--------------------------------

### Prompt Assembly Utility

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/module_api.md

Constructs structured prompts using XML-style blocks for task definition and output contracts.

```ts
export function assemblePrompt(args: {
  prompt: string;
  schema?: Record<string, unknown>;
  profilePreamble?: string;
}): string;
// XML-ish blocks (codex plugin's gpt-5-4 prompting):
// <task>{prompt}</task>
// output contract block: RETURN_VALUE_CONTRACT + (schema ? schemaInstruction : plain-text contract)
// <default_follow_through_policy>: never stop to ask questions; act on stated defaults; finish.
// profilePreamble (if any) prepended as its own paragraph.
```

--------------------------------

### Run an agent loop with completion criteria

Source: https://github.com/yuanpingsong/ultracodex/blob/main/README.md

Executes a task until the specified criteria are met, governed by a token budget.

```bash
ultracodex run goal --args '{
  "task": "Implement the CSV import endpoint",
  "criteria": "Build passes. Tests pass. Malformed rows are rejected with row-level errors."
}' --budget 250k
```

--------------------------------

### ultracodex schedule ls

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/schedule.md

Lists all currently configured schedules.

```APIDOC
## ultracodex schedule ls [--json]

### Description
Displays a list of all scheduled tasks. Use the --json flag to output the list in JSON format.
```

--------------------------------

### Run a packaged loop

Source: https://github.com/yuanpingsong/ultracodex/blob/main/skills/ultracodex/SKILL.md

Executes a named workflow with specific budget and criteria constraints. The process runs until the verifier confirms the criteria or the backlog is empty.

```bash
ultracodex run goal --json --budget 300k --args '{"task":"...","criteria":"explicit, verifier-checkable"}'
```

--------------------------------

### UltraCodex Execution Flow

Source: https://github.com/yuanpingsong/ultracodex/blob/main/README.md

Mermaid diagram illustrating the script loading, runtime execution, and journaling process.

```mermaid
flowchart LR
    S["script.js"] --> L["loader<br/>acorn meta-parse + vm"]
    L --> R["runtime<br/>semantics · caps · budget · semaphore"]

    subgraph EX["executors — one per route"]
        direction TB
        CX["codex<br/>codex app-server · JSON-RPC<br/>one process per slot"]
        OC["opencode<br/>opencode serve · HTTP + SSE<br/>one server per call"]
        CL["claude<br/>headless claude -p"]
    end

    R --> CX & OC & CL

    R -.->|every event| J[("journal.jsonl")]
    CTL[("control.jsonl")] -.->|pause · stop · skip| R
    J --> OBS["TUI · show · --json<br/>pure folds over the journal"]
```

--------------------------------

### Arguments-driven Brief Override

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/design-exploration/README.md

Allows callers to inject custom briefs to increase component reusability.

```javascript
args?.brief
```

--------------------------------

### Configuration Management API

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/module_api.md

Handles loading project configurations from TOML files and provides routing logic for backend selection based on glob patterns.

```typescript
export function loadConfig(projectDir: string): UltracodexConfig;
// merge order: DEFAULT_CONFIG ← ~/.ultracodex/config.toml ← <projectDir>/.ultracodex/config.toml
// TOML shape mirrors docs/internal/product_context.md §2: [route] table (key=pattern, value=backend,
// preserves file order; a "*" fallback appended if absent), [backends.codex], [backends.claude],
// [profiles.<name>]. Unknown keys ignored with no error. concurrency under top-level [run] table
// optional: run.concurrency.
export function matchGlob(pattern: string, value: string): boolean; // '*' wildcard segments only
export function routeBackend(config: UltracodexConfig, label: string, phase: string | null): string;
// label matched first against every rule in order, then phase; first match wins; default "codex"
```

--------------------------------

### Execute map-over-corpus workflow

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/map-over-corpus/README.md

Run the workflow with a specified budget and input arguments. Ensure the catalog path is an absolute path to a valid JSON array.

```bash
ultracodex run examples/map-over-corpus/workflow.js --budget 500k \
  --args '{"catalog":"/abs/path/to/catalog.json","count":500}'
```

--------------------------------

### ultracodex utility commands

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/product_context.md

System utility commands for validation, synchronization, and diagnostics.

```APIDOC
## Utility Commands

### Commands
- `ultracodex validate <script.js>` - Performs compatibility linting on a script.
- `ultracodex sync-skills` - Synchronizes static and workflow-specific skills.
- `ultracodex doctor` - Performs system checks (node version, auth, config) and provides actionable next steps.
```

--------------------------------

### goal

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/loops.md

Executes a builder agent and a verifier agent to complete a specified task based on provided criteria.

```APIDOC
## goal

### Description
Runs one builder agent and one skeptical verifier agent per round to complete a task based on explicit criteria.

### Parameters
- **task** (string) - Required - What to build or do.
- **criteria** (string) - Required - Explicit verifier-checkable acceptance criteria.
- **maxRounds** (number) - Optional - Positive integer round cap (default: 4).
- **context** (string) - Optional - Paths or notes included in builder and verifier prompts.
- **builderModel** (string) - Optional - Passed as model only when provided.
- **verifierModel** (string) - Optional - Passed as model only when provided.
- **budgetFloor** (number) - Optional - If budget is set and remaining output tokens are below this, the loop stops (default: 20000).

### Response
- **done** (boolean) - Indicates if the verifier approved.
- **rounds** (number) - Total rounds executed.
- **verdict** (string) - The final outcome: 'approved', 'rejected', or 'exhausted'.
- **issues** (array) - List of issues identified.
- **history** (array) - Detailed history of each round.
```

--------------------------------

### Execute skill validation rounds

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/research/skill-validation/README.md

Commands to generate the harness, configure the project, and run the validation matrix for different driver backends.

```bash
# 1. folders (L4 wants a seeded completed run)
SKILLVAL_L4_SEED=<path-to-a-completed-goal-run-dir> \
  python3 fleet/skillval-gen.py /tmp/skillval-harness/rN

# 2. harness project config: see the [route] table in this doc's appendix —
#    driver:cx-*→codex(terra), driver:cl-*→claude(sonnet-5),
#    driver:oc-*→opencode, judge:*→claude(sonnet-5), plus
#    [profiles.Networked] for the codex drivers.

# 3. main matrix
cd /tmp/skillval-harness && ultracodex run <repo>/fleet/skill-validation.js \
  --json --concurrency 6 --args '{"base":"/tmp/skillval-harness/rN","backends":["cx","cl"]}'

# 4. opencode separately — low concurrency, isolated state
mkdir -p /tmp/oc-data/opencode && cp ~/.local/share/opencode/auth.json /tmp/oc-data/opencode/
XDG_DATA_HOME=/tmp/oc-data ultracodex run <repo>/fleet/skill-validation.js \
  --json --concurrency 2 --args '{"base":"/tmp/skillval-harness/rN","backends":["oc"]}'
```

--------------------------------

### Configure backend routing and model mapping

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/product_context.md

Defines the routing logic for agent labels and phases, alongside backend-specific settings for codex and claude. Ensure the file is located at .ultracodex/config.toml to be correctly parsed by the runner.

```toml
# .ultracodex/config.toml
[route]                       # matched against agent label, then phase
"critique:*" = "claude"       # fable verifies
"*"          = "codex"        # codex executes

[backends.codex]
sandbox = "workspace-write"
default_model = "gpt-5.5"   # codex's own default (live lineup, probe 2026-07-02)
default_effort = "xhigh"    # unpinned agents get max effort, not codex's medium
service_tier = "standard"   # fast mode OFF by default even if ~/.codex enables it
model_map = { fable = "gpt-5.5", opus = "gpt-5.5", sonnet = "gpt-5.4", haiku = "gpt-5.4-mini", spark = "gpt-5.3-codex-spark" }
effort_map = { low = "low", medium = "medium", high = "high", xhigh = "xhigh", max = "xhigh" }

[backends.claude]             # M3: shells to `claude -p --output-format json`
```

--------------------------------

### Implement iterative agent loops

Source: https://github.com/yuanpingsong/ultracodex/blob/main/skills/agent-script-authoring/SKILL.md

Use standard JavaScript loops for iterative agent tasks, ensuring early exit conditions and proper phase labeling for engine tracking.

```javascript
let draft = null, verdict = null
for (let round = 1; round <= MAX_ROUNDS; round++) {
  const next = await agent(round === 1 ? DRAFT_PROMPT : revisePrompt(draft, verdict.issues), { phase: `Round ${round}` })
  if (!next) break
  draft = next
  verdict = await agent(critiquePrompt(draft), { schema: VERDICT_SCHEMA, phase: `Round ${round}` })
  if (verdict?.pass) break                      // early exit on first pass
}
```

--------------------------------

### schemaInstruction

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/module_api.md

Generates a structured output contract string based on a provided JSON schema.

```APIDOC
## schemaInstruction(schema: Record<string, unknown>): string

### Description
Creates a formatted string instruction for LLMs to respond with a single JSON object valid against the provided schema.

### Parameters
- **schema** (Record<string, unknown>) - Required - The JSON schema to be inlined into the contract.
```

--------------------------------

### Run Agent Scripts

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/README.md

Commands to execute specific agent workflow scripts using the ultracodex CLI, with optional flags for monitoring and budget constraints.

```bash
ultracodex run examples/hello/workflow.js --watch
ultracodex run examples/fanout-synthesize/workflow.js
ultracodex run examples/actor-critic-loop/workflow.js --watch --budget 200k
```

--------------------------------

### Add new schedules

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/schedule.md

Commands to define new schedules with varying cadences, budgets, and execution commands.

```bash
ultracodex schedule add digest --every 30m --budget 200k -- run digest.js
ultracodex schedule add nightly --daily 18:30 --budget 300k -- run nightly-review
ultracodex schedule add cleanup --cron "15 9 * * 1" -- node scripts/cleanup.mjs
```

--------------------------------

### Phase Grouping for Progress Tracking

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/design-exploration/README.md

Uses phase markers to align execution steps with UI progress displays.

```javascript
phase('Diverge') / phase('Converge')
```

--------------------------------

### Test with ULTRACODEX_CRONTAB_FILE

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/schedule.md

Use this environment variable to redirect scheduler operations to a temporary file instead of the system crontab.

```bash
tmp=$(mktemp -d)
ULTRACODEX_CRONTAB_FILE="$tmp/crontab" ultracodex schedule add demo --every 5m -- node -e 'console.log("ok")'
cat "$tmp/crontab"
```

--------------------------------

### ultracodex management commands

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/product_context.md

Commands for managing the lifecycle of active runs including listing, attaching, pausing, resuming, and terminating.

```APIDOC
## Management Commands

### Commands
- `ultracodex ls` - Lists runs and their statuses.
- `ultracodex attach <runId>` - Attaches the TUI to a live run.
- `ultracodex pause <runId>` - Pauses a live run.
- `ultracodex resume <runId>` - Resumes a paused run.
- `ultracodex kill <runId>` - Terminates a run.
- `ultracodex skip <runId> <n>` - Skips n steps in a run.
- `ultracodex logs <runId> [<n>]` - Retrieves raw agent events for a run.
```

--------------------------------

### Schedule daily org-tick command

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/org.md

Configures a daily execution of the org-tick command at 18:30 local time.

```bash
ultracodex schedule add org-tick --daily 18:30 -- ultracodex org tick
```

--------------------------------

### Define Script Metadata and Body

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/product_context.md

The script must export a pure meta object literal followed by an async body. The meta object requires name and description fields, with optional phases for progress tracking.

```js
export const meta = {
  name: 'kebab-case-id',          // required
  description: 'one-liner',       // required
  whenToUse: '...',               // optional
  phases: [                       // optional; titles string-match phase() calls
    { title: 'Draft', detail: '...' },
    { title: 'Critique', detail: '...', model: 'opus' },  // per-phase model override
  ],
}
// body: top-level await allowed; return value = workflow result
```

--------------------------------

### Application Server Client Interface

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/module_api.md

Client implementation for communicating with the application server using JSONL over stdin/stdout with support for requests, notifications, and process lifecycle management.

```ts
export interface AppServerClientOptions {
  binary: string;               // "codex" or the fake
  cwd: string;
  env?: NodeJS.ProcessEnv;
}
export class RpcError extends Error { code?: number; data?: unknown }
export class AppServerClient {
  static start(opts: AppServerClientOptions): Promise<AppServerClient>;
  // spawn(binary, ["app-server"], {stdio: pipe*3}); JSONL over stdin/stdout; perform
  // initialize handshake (clientInfo name "ultracodex", opt out of delta notifications:
  // item/agentMessage/delta, item/reasoning/summaryTextDelta, item/reasoning/summaryPartAdded,
  // item/reasoning/textDelta) then send `initialized` notification.
  request<T = unknown>(method: string, params: unknown, opts?: { timeoutMs?: number }): Promise<T>;
  notify(method: string, params: unknown): void;
  onNotification(handler: (method: string, params: unknown) => void): () => void;
  // Server→client REQUESTS (messages with id + method, e.g. approval asks): respond
  // automatically with {decision: "denied"} and surface via onNotification too.
  close(): Promise<void>;      // end stdin, wait exit w/ 2s timeout, then SIGKILL process tree
  kill(): void;                // immediate SIGKILL process tree
  readonly pid: number | null;
  readonly exited: Promise<number | null>;
}
```

--------------------------------

### Capability Descriptor Configuration

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/research/opencode-probe.md

Defines the operational capabilities and constraints for the adapter, including session persistence and interruption handling.

```json
{
  schema: "wire",          // + per-call fallback to prompt-only on APIError/StructuredOutputError
  resume: true,            // sessions persist; repair turns POST to the same session
  interrupt: "graceful",   // /abort acks, message settles typed; SIGTERM serve after settle
  usage: "per-turn",       // message.updated SSE ticks; sync response is the authoritative final
  activity: true,          // message.part.delta stream
  sandbox: [] }            // NO OS sandbox — engine warns per contract §3; the adapter
                           // additionally applies the tools-disable map for read-only-ish
                           // profiles as defense-in-depth (documented, not a sandbox claim)
```

--------------------------------

### Regenerate fleet usage metrics

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/research/v050-fleet-usage.md

Calculates total output tokens per run by parsing agent_usage and agent_end events from journal.jsonl files.

```python
# from the repo root
import json, glob
for j in glob.glob('.ultracodex/runs/*/journal.jsonl'):
    per = {}
    for line in open(j):
        e = json.loads(line)
        if e.get('t') in ('agent_usage','agent_end') and e.get('usage'):
            per[e['n']] = e['usage'].get('outputTokens', 0)
    print(j, len(per), sum(per.values()))
```

--------------------------------

### ultracodex show

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/product_context.md

Displays the status and output of a specific run identified by its runId.

```APIDOC
## ultracodex show

### Description
Retrieves the journal or machine output for a specific run. Can optionally block until the run completes.

### Usage
`ultracodex show <runId> [--json] [--wait [--timeout-ms N]]`

### Parameters
- **runId** (string) - Required - The unique identifier or prefix for the run.

### Options
- **--json** (flag) - Optional - Output as JSON.
- **--wait** (flag) - Optional - Blocks until the run ends.
- **--timeout-ms** (number) - Optional - Timeout duration in milliseconds for the wait operation.
```

--------------------------------

### Synchronize Skills Module API

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/module_api.md

Copies static skills and generates dynamic skill definitions from workflow metadata. Throws an error if the source directory is missing.

```ts
export function syncSkills(projectDir: string): { written: string[] };
```

--------------------------------

### Memory File YAML Frontmatter

Source: https://github.com/yuanpingsong/ultracodex/blob/main/org-templates/roles/entity.md

Required header for all memory files including BRIEF, THESIS, IDENTITY, LOG, and WATCHLIST.

```yaml
---
updated: YYYY-MM-DD
sources: [files this content rests on]
confidence: speculative | possible | likely | high-confidence
next_review: YYYY-MM-DD
---
```

--------------------------------

### Manage existing schedules

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/schedule.md

Commands to list, pause, resume, or remove defined schedules.

```bash
ultracodex schedule ls
ultracodex schedule pause digest
ultracodex schedule resume digest
ultracodex schedule rm digest
```

--------------------------------

### Run Directory Management API

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/module_api.md

Handles directory structure creation, PID file management, and run identification for project execution environments.

```ts
export function stateDir(projectDir: string): string;                    // <projectDir>/.ultracodex
export function runsDir(projectDir: string): string;
export function createRunDir(projectDir: string, runId: string): string; // mkdir -p runs/<runId>/agents
export function writePidFile(runDir: string, pid: number): void;
export function readPid(runDir: string): number | null;
export function pidAlive(pid: number): boolean;                          // process.kill(pid, 0)
export function agentDir(runDir: string, n: number, label: string): string; // agents/<n>-<slug> (mkdir)
export function listRuns(projectDir: string): RunSummary[];              // newest first; folds journal
export function resolveRunId(projectDir: string, ref: string): string;
// exact match, else unique-prefix; ambiguous → throw Error listing candidates; none → throw
```

--------------------------------

### agent(prompt, opts?)

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/agent-script-spec.md

Invokes an agent to process a prompt and return a result based on the provided schema or raw text.

```APIDOC
## agent(prompt, opts?) 

### Description 
Invokes an agent to process a prompt. Resolves to the agent's final message string or an object if a JSON schema is provided. 

### Parameters 
- **prompt** (string) - Required - The prompt to be processed. 
- **opts** (object) - Optional - Configuration options including label, phase, schema, model, effort, isolation, and agentType. 

### Returns 
- **Promise<string | object | null>** - Resolves to the result or null on failure. Throws on budget exhaustion or lifetime/fan-out cap violations.
```

--------------------------------

### Org filesystem structure

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/org.md

The directory layout for an Org, organized into a two-to-three-level tree of root, group, and entity agents.

```text
/                         root agent
  AGENTS.md BRIEF.md LOG.md inbox/ tickets/
  coverage.toml           groups + entities
  templates/              root.md group.md entity.md
  <group>/                aggregator
    AGENTS.md BRIEF.md THESIS.md LOG.md inbox/ tickets/
    <entity>/             leaf agent
      AGENTS.md BRIEF.md IDENTITY.md THESIS.md LOG.md WATCHLIST.md
      FACTS/ inbox/ tickets/
  ingest/                 ledger.jsonl cache/ unassigned/
  .ultracodex/org/state/  runtime state
```

--------------------------------

### UltraCodex State Directory Layout

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/operations.md

The standard directory structure for an UltraCodex project, including configuration, workflows, and run logs.

```text
.ultracodex/
  config.toml          # [route] label/phase globs → backend; [backends.*] maps
  workflows/<name>.js  # saved workflows (meta.name must match filename)
  runs/<runId>/        # journal.jsonl (spine), control.jsonl, pid, agents/<n>/,
                       # script.js + args.json snapshots, result.json
  org/state/           # last-wake.json, audit-history.jsonl
```

--------------------------------

### Define Run control commands

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/product_context.md

Commands appended to control.jsonl to manage runner state, including stopping, pausing, and skipping agents.

```jsonc
{"cmd":"stop"}            // graceful: cancel queued agents, terminate children, run_end: stopped
{"cmd":"pause"}           // SOFT pause: stop launching new agents; in-flight codex
                          // processes run to completion. This is the only pause in v1.
{"cmd":"resume"}
{"cmd":"skip","n":4}      // resolve agent n to null (kills its process)
```

--------------------------------

### Run research sweep with custom areas

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/research-sweep/README.md

Extends the default target list by passing custom areas via the --args flag.

```bash
ultracodex run examples/research-sweep/workflow.js --watch --args '{"areas":[{"area":"NAS","prompt":"Investigate /mnt/nas ..."}]}'
```

--------------------------------

### Codex App-Server RPC Flow

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/product_context.md

Outlines the sequence of JSON-RPC commands for initializing and running a turn within the codex app-server process.

```text
spawn: codex app-server            (stdio pipes; cwd = agent cwd)
rpc:   initialize
       thread/start                → threadId
       turn/start {threadId, input, model, effort, outputSchema}
       … notifications …          → turn/completed
```

--------------------------------

### CaptureTurn State Machine Logic

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/module_api.md

Outlines the event handling and state transitions for the turn lifecycle, including event routing, activity mapping, and completion inference.

```ts
// The captureTurn state machine (see docs/internal/product_context.md §3.3 and the codex plugin):
// - send turn/start {threadId, input: [{type:"text", text: prompt, text_elements: []}], model,
//   effort, outputSchema}; response carries turn id — but notifications may arrive first: buffer
//   notifications until turnId known, then route by threadId+turnId (accept subagent thread events).
// - item/started + item/completed → describeItem → onActivity (kind mapping: commandExecution→exec
//   w/ VERIFICATION_COMMAND_RE phase, fileChange→patch, mcpToolCall/dynamicToolCall/
//   collabAgentToolCall→tool, webSearch→search, reasoning→reasoning, others→status).
// - agentMessage item/completed with phase "final_answer" → record text, mark finalAnswerSeen.
// - collabAgentToolCall started/completed tracked as pendingCollabs; turn/started on OTHER threadIds
//   tracked as activeSubagentTurns, removed on their turn/completed.
// - thread/tokenUsage/updated for threadId → usage = last (per-turn); emit onUsage.
// - turn/completed for main turn → resolve. If finalAnswerSeen and pendingCollabs+subagent turns
//   empty but no turn/completed after INFER_COMPLETION_MS → resolve as completed (inferred).
// - `error` notification → resolve failed with message.
// - abort signal → request turn/interrupt {threadId, turnId}; if no turn/completed within
//   INTERRUPT_GRACE_MS resolve "interrupted" anyway (caller kills client).
```

--------------------------------

### Define Adapter Capabilities

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/agent-script-plan.md

The capability descriptor defines the operational constraints and features supported by an adapter, including schema types, resumption, and sandbox profiles.

```json
{
  schema: "wire" | "prompt-only",
  resume: boolean,            // continuation turns for schema repair
  interrupt: "graceful" | "kill-only",
  usage: "per-turn" | "final" | "none",
  activity: boolean,          // streamed events for the TUI
  sandbox: string[] }
```

--------------------------------

### Render Static Run Journal

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/module_api.md

Generates a one-shot string representation of a run journal, including phase strips and agent lines.

```ts
export function renderRunStatic(state: TuiState, opts?: { color?: boolean }): string;
```

--------------------------------

### Run research sweep workflow

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/research-sweep/README.md

Executes the workflow using the default baked-in targets.

```bash
ultracodex run examples/research-sweep/workflow.js --watch
```

--------------------------------

### Reference Skill for Codex

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/skills.md

Instructions for referencing the agent-script-authoring skill within a Codex prompt.

```text
Author the workflow per skills/agent-script-authoring/SKILL.md (bundled in the
ultracodex package), save it to a file, and run `ultracodex run <file> --json`.
```

--------------------------------

### ultracodex schedule add

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/schedule.md

Adds a new scheduled command with a specified cadence and optional constraints.

```APIDOC
## ultracodex schedule add <name> (--every <dur> | --daily <HH:MM> | --cron "<expr>") [--until-done] [--max-runs <n>] [--budget <spec>] -- <command...>

### Description
Registers a new scheduled task. The name must be a lowercase slug (letters, digits, hyphens).

### Parameters
- **name** (string) - Required - Unique identifier for the schedule.
- **--every** (duration) - Optional - Cadence in minutes (e.g., 1m, 30m) or hours (e.g., 1h, 12h).
- **--daily** (HH:MM) - Optional - Daily execution time.
- **--cron** (string) - Optional - Standard 5-field cron expression.
- **--until-done** (flag) - Optional - Run until completion.
- **--max-runs** (integer) - Optional - Hard limit on the number of executions.
- **--budget** (string) - Optional - Token budget for the execution (e.g., 200k).
- **--command** (string) - Required - The command to execute.
```

--------------------------------

### Run TUI Interface

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/module_api.md

Initializes the terminal user interface. Quitting the TUI does not terminate active runs.

```ts
export function runTui(opts: { projectDir: string; runDir?: string }): Promise<void>;
```

--------------------------------

### Provenance Tagging Implementation

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/design-exploration/README.md

Records the origin direction of a proposal while ensuring null failures remain falsy.

```javascript
.then((p) => (p ? { ...p, _direction: D.key } : null))
```

--------------------------------

### workflow(nameOrRef, args?)

Source: https://github.com/yuanpingsong/ultracodex/blob/main/docs/internal/product_context.md

Executes a saved workflow inline within the current execution context.

```APIDOC
## workflow(nameOrRef, args?)

### Description
Runs a saved workflow. Shares concurrency, budget, and abort state. Limited to one level of nesting.
```

--------------------------------

### Null-tolerant Fan-out Filtering

Source: https://github.com/yuanpingsong/ultracodex/blob/main/examples/design-exploration/README.md

Filters out failed proposals and ensures empty results are handled gracefully.

```javascript
.filter(Boolean)
```