Orchestrate run-agent

Agent execution engine that composes prompts, routes models, and writes run artifacts. Use when launching subagent runs.

install

source · Clone the upstream repo

git clone https://github.com/haowjy/orchestrate

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/haowjy/orchestrate "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/run-agent" ~/.claude/skills/haowjy-orchestrate-run-agent && rm -rf "$T"

manifest: .claude/skills/run-agent/SKILL.md

source content

Run-Agent — Execution Engine

Single entry point for agent execution. A run is

model + agent (opt) + skills (opt) + prompt

. Routes to the correct CLI (

claude

codex

opencode

) based on the model, logs everything, and writes structured index entries.

Skills source: sibling skills (

../

). Runtime artifacts:

.orchestrate/

Runner scripts (relative to this skill directory):

```
scripts/run-agent.sh
```
— launch a subagent run
```
scripts/run-index.sh
```
— inspect and manage runs

Run Composition

Compose runs dynamically by specifying model, skills, and prompt:

# Model + skills + prompt
scripts/run-agent.sh --model MODEL --skills SKILL1,SKILL2 -p "PROMPT"

# Model + prompt (no skills)
scripts/run-agent.sh --model MODEL -p "PROMPT"

# With labels and session grouping
scripts/run-agent.sh --model MODEL --skills SKILLS \
    --session SESSION_ID --label KEY=VALUE -p "PROMPT"

# With template variables
scripts/run-agent.sh --model MODEL \
    -v KEY1=path/to/file1 -v KEY2=path/to/file2 \
    -p "Task using {{KEY1}} and {{KEY2}}"

# Dry run — see composed prompt + CLI command without executing
scripts/run-agent.sh --model MODEL --skills SKILLS --dry-run -p "PROMPT"

Key Flags

Flag	Description
`--model MODEL` / `-m`	Model to use (auto-routes to correct CLI)
`--agent NAME`	Agent profile for defaults + permissions
`--skills a,b,c`	Skills to compose into the prompt
`--strict-skills`	Fail fast when any listed skill is unknown
`-p "prompt"`	Task prompt
`-f path/to/file`	Reference file appended to prompt
`-v KEY=VALUE`	Template variable substitution (repeatable)
`--session ID`	Session ID for grouping related runs
`--label KEY=VALUE`	Run metadata label (repeatable)
`-D brief\|standard\|detailed`	Report detail level (default: `standard` )
`--continue-run REF`	Continue a previous run's harness session
`--fork`	Fork the session on continuation (default where supported)
`--in-place`	Resume without forking (always for Codex)
`--dry-run`	Show composed prompt without executing
`-C DIR`	Working directory for subprocess

Runtime Config (

.orchestrate/config.toml

)

On first run in a workspace,

run-agent.sh

auto-creates

.orchestrate/config.toml

with commented examples.

Use this file to pin skills that should be auto-added on every run:

[skills]
pinned = ["orchestrate", "run-agent", "mermaid"]

Notes:

Pinned skills are merged with agent-profile skills and CLI
```
--skills
```
(deduplicated by name).
Default template is fully commented; uncomment/edit to enable.

Output Artifacts

Each run writes to

.orchestrate/runs/agent-runs/<run-id>/

```
params.json
```
— run parameters and metadata
```
input.md
```
— composed prompt
```
prompt.raw.md
```
— composed prompt before runtime-generated output/report sections
```
output.jsonl
```
— raw CLI output (stream-json or JSONL)
```
stderr.log
```
— CLI diagnostics (also streamed to terminal)
```
report.md
```
— written by the subagent (or extracted as fallback)
```
files-touched.nul
```
— NUL-delimited file paths (canonical machine format)
```
files-touched.txt
```
— newline-delimited file paths (human-readable)

Run Index

Two-row append-only index at

.orchestrate/index/runs.jsonl

Start row (written before execution):
```
status: "running"
```
— provides crash visibility.
Finalize row (written after execution):
```
status: "completed"|"failed"
```
with exit code, duration, token usage, git metadata.

A start row with no matching finalize row means the run crashed or is still in progress.

Structured Exit Codes

Code	Meaning
0	Success
1	Agent/model error (bad output, task failure)
2	Infrastructure error (CLI not found, harness crash)
3	Timeout
130	Interrupted (SIGINT / user cancel)
143	Terminated (SIGTERM)

Model Routing

Pattern CLI

claude-*

opus*

sonnet*

haiku*

Claude (

claude -p

)

gpt-*

o1*

o3*

o4*

codex*

Codex (

codex exec

)

opencode-*

provider/model

OpenCode (

opencode run

)

Routing is automatic from the selected model.

Run Explorer CLI

scripts/run-index.sh

provides index-based run inspection:

scripts/run-index.sh list                          # List recent runs
scripts/run-index.sh list --failed --json          # Failed runs as JSON
scripts/run-index.sh show @latest                  # Show last run details
scripts/run-index.sh report @latest                # Read last run's report
scripts/run-index.sh logs @latest --tools          # Tool call summary
scripts/run-index.sh files @latest                 # Files touched
scripts/run-index.sh stats                         # Aggregate statistics
scripts/run-index.sh continue @latest -p "PROMPT"  # Continue a run's session
scripts/run-index.sh retry @last-failed            # Retry a failed run
scripts/run-index.sh maintain --compact            # Archive old index entries

Run references: full ID, unique prefix (8+ chars),

@latest

@last-failed

@last-completed

Helper Scripts

Script	Purpose
`run-index.sh`	Run explorer CLI (list, show, report, logs, files, stats, continue, retry, maintain)
`log-inspect.sh`	Inspect run logs (summary, tools, errors, files, search)
`extract-files-touched.sh`	Extract file paths from run output
`extract-harness-session-id.sh`	Extract harness session/thread ID from output
`extract-report-fallback.sh`	Extract last assistant message as report fallback
`load-model-guidance.sh`	Load model guidance with override precedence