ultracodex

https://github.com/yuanpingsong/ultracodex
Admin
ultracodex is a developer tool and runtime that runs unmodified Claude Code workflow scripts on...
Tokens:48,889
Snippets:682
Trust Score:7.3
License:Apache-2.0
Update:2 months ago
Show doc for...
Tokens:
Raw
### 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
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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 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
```

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

### 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 }
```

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

### 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
```

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

### 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 })
```

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

### 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 ...]
```

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

### 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"}'
```
Tokens:
Raw