Onyx Agent

Open-source agent package for Onyx research workflows.

It installs the onyx command and the bundled onyx agent skill. The command is terminal-only: agents make code changes in your existing git repository, commit measured attempts, push immutable experiment refs best-effort, and report experiment metadata plus setup, hypothesis, and worker state to the Onyx app.

Install

curl -fsSL https://onyxresearch.ai/install.sh | bash

The installer puts onyx in ~/.local/bin by default, walks you through PATH setup if your shell needs it, and then starts browser login. Press Esc while it is waiting if you need to authenticate later or use ONYX_API_KEY instead.

Verify the command:

onyx --version

For non-interactive installs, set ONYX_INSTALL_NO_PROMPT=1. For explicit system-wide installs, choose a writable install directory:

curl -fsSL https://onyxresearch.ai/install.sh | ONYX_INSTALL_DIR=/usr/local/bin bash

If you cancel authentication during install, run onyx login later.

Profiles are team-scoped. Use onyx profile list, onyx profile use <name>, and onyx profile delete <name> to inspect, switch, or remove local profile entries; profile listing includes each profile's worker defaults. Use onyx profile worker set --agent codex|claude|opencode [--model <model>] to store default worker settings for new research sessions; --agent and --model flags on onyx research run override those defaults.

Only for local app development, point the agent at a non-production API. --local is shorthand for --api-url http://localhost:3000:

onyx login --local

This stores a separate profile for the local app; switch between it and the hosted app with onyx profile use <name>. Developer mode (onyx developer use dev) changes which CLI source runs, not which app the CLI targets.

Agent Skill

The installer installs the bundled skill automatically for Claude Code, Codex, and OpenCode. It writes Claude's personal skill file at ~/.claude/skills/onyx/SKILL.md, Codex's user skill file at ~/.agents/skills/onyx/SKILL.md, the Codex home skill file at ${CODEX_HOME:-~/.codex}/skills/onyx/SKILL.md for Codex builds that discover skills from CODEX_HOME, and OpenCode's global skill file at ~/.config/opencode/skills/onyx/SKILL.md. The canonical source is skills/onyx/SKILL.md; after editing it, run bun run generate:skill-content so the embedded release fallback stays in sync. To install it manually:

onyx agent install-skill

To locate the package skill source:

onyx agent skill-path

Core Workflow

onyx setup init --goal "Improve score" --metric-name score --editable-scope src --eval-command "printf 'METRIC score=1\n'"
# edit onyx/setup.json, onyx/onyx.md, and onyx/tools/evaluation/run.sh
onyx setup validate
git add onyx
git commit -m "Add Onyx setup"
git push origin HEAD
onyx campaign setup --name fast-eval --description "Improve score"
onyx research run --campaign fast-eval --workers 4
onyx listen

The CLI writes research product state directly to /api/v1. Supabase/API owns campaigns, sessions, hypotheses, worker leases, experiments, summaries, knowledge, stop state, report settlement, and accepted experiment ordering. Local .git/onyx/ files are runtime artifacts: logs, manifests, workflow runs, attempts, session-state briefs, resource locks, and a small state.json convenience cache. Transient diagnostics use onyx tools run <tool-id>, which executes declared setup tools without creating workflow or measured-attempt state.

The bundled /onyx skill is the preferred user-facing orchestrator. It creates onyx/setup.json, onyx/validation.json, generated onyx/onyx.md, and onyx/tools/*; designs the linear workflow and declared tools; validates the setup hash and executes the canonical metric tool once to prove readiness; then creates an async research session with deliberate hypothesis plans. Runtime rigor remains in onyx exp run, which pauses for the agent edit, requires exactly one clean result commit, executes workflow command steps, parses the primary metric, and records setup compliance. onyx setup init stays explicit: --editable-scope and --eval-command write only the caller-provided values, and the default eval tool keeps failing until the orchestrator deliberately configures it. Slow eval cost is paid during onyx setup validate, not before every worker loop. The generated onyx/onyx.md is a research spec for durable project guidance: goal, metric interpretation, editable scope, evaluation caveats, declared tools, and project-specific constraints. The supervisor writes a shared local session-state brief for routine worker context; workers use targeted CLI commands only when they need deeper prose memory or history.

Research commands require API access. The supervisor uses server-assigned leases, renews worker liveness in batches, and owns stop scheduling. Workers attempt to push immutable experiment refs while reporting; failed pushes are recorded as local-reported evidence instead of blocking metrics. Experiment report calls return recorded or duplicate, and later settlement assigns accepted/discarded disposition plus accepted indexes. onyx exp list, onyx research status, onyx listen, knowledge list, and summary list read remote API state instead of offline local projections.

onyx campaign setup and onyx research run require the onyx/ setup surface to be committed. This keeps worker worktrees pinned to a base commit that actually contains setup.json, validation.json, onyx.md, and declared workflow tools. GitHub App access is optional for local research: public repositories can show web code/diffs once commits and refs are pushed to GitHub, while private repositories record local-reported commits and metrics until the GitHub App is connected for private code/diff viewing and verification. After pushing missing refs or connecting GitHub, use the web campaign page or onyx research status --reconcile to refresh Git verification state.

Tool commands in onyx/setup.json are language-flexible: point them at Bash, Python, Node, hardware vendor CLIs, compiled binaries, or any executable available to the project.

Hypothesis workers are driven by the TypeScript-rendered Markdown prompt in src/lib/worker-prompt.ts, so prompt variables are typechecked directly in the editor and standalone release binaries stay self-contained.

To run multiple local research hypotheses directly from the CLI, use the repo-level supervisor with a built-in agent launcher:

plans='[{"focus":"Try a bounded search","statement":"A focused local change can improve the configured metric."}]'
onyx research run --campaign fast-eval --workers 4 --agent codex --hypotheses "$plans" --max-minutes 10 --experiments 20
onyx research hypothesis add --session <id> --focus "Try a fresh hypothesis" --hypothesis "The new direction may improve score"

onyx research run validates the campaign and starts a detached supervisor by default, then prints the session id, supervisor PID, log path, and monitoring commands before returning. Use --json for parseable startup output in orchestrator agents, and --foreground only when you intentionally want an attached debugging or smoke-test shell.

--workers is the active slot target: when a short worker exits, the supervisor backfills that slot while the session is running. Bound sessions with --experiments <n> for an exact accepted experiment target, --max-minutes <n> for a deadline, or both:

onyx research run --campaign fast-eval --workers 2 --max-concurrency 2 --experiments 2 --worker-command "<cmd>"

For large local runs, the supervisor ramps launches in batches (--launch-batch-size, default up to 10) separated by --launch-interval-seconds (default 5), backs off with capped exponential jitter when provider startup, rate-limit, overload, auth, or degraded-service failures happen, and asks the server for worker leases in idempotent batches. The server enforces the worker target, assigns hypotheses, records reports, and settles accepted/discarded disposition idempotently after completion.

Presence is bounded for large sessions: the supervisor sends site telemetry every interval while uploading changed worker snapshots by default, a full worker snapshot every 60 seconds or final upload, and at most 250 worker snapshots per request.

Codex, Claude, and OpenCode are first-class built-in launchers. All are spawned directly in non-interactive mode, receive the worker prompt over stdin, and use the explicit onyx-worker CLI surface for worker-safe primitives while the full onyx CLI remains the user/orchestrator surface. Supervised workers get isolated ONYX_HOME plus ONYX_WORKER_CONTEXT under .git/onyx/worker-runtime/<session>/<workerId>/, and write raw stdout/stderr logs, readable .activity.log files, structured .activity.jsonl files, per-worker latest-state JSON snapshots, and launch manifests under .git/onyx/worker-logs/. onyx research run owns local worker scheduling, server lease acquisition, session-state brief refreshes, adaptive coalesced presence updates, batch heartbeats, stop handling, and local child cleanup. onyx research status --json reports fresh supervisor telemetry when available, including active process count, launch rate, provider backoff, recent launch failures, PID, and log path. onyx worker run --session <id> --hypothesis <id> remains available as a low-level debugging and recovery primitive. onyx research status shows active-session hypotheses and workers by default, including activity/raw log paths, last-output age, timeout state, and manifest errors when local manifests are available. --experiments is the exact accepted experiment target and --max-minutes is the optional deadline. onyx listen shows the same local worker latest-state/manifests and active provider backoff metadata alongside the experiment/outbox view. onyx workflow status --active shows only actionable running or paused workflow runs; use onyx workflow status --blocked or --run <id> for blocked diagnostics.

Each worker gets its own work branch under refs/heads/onyx/<session>/<worker>, and its worktree lives at .git/onyx/worktrees/<sessionId>/<workerId>, while worker prompts and logs live under .git/onyx/. Workers run onyx-worker research session-state-brief --json for routine context and worker-specific stop guidance. They inspect stop.shouldStopStartingNewWork and stop.recommendedAction at the start of each loop, use onyx-worker research brief only for fuller prose memory, run the setup workflow through onyx-worker exp run --campaign <name> --auto and onyx-worker exp run --resume --auto, push refs/onyx/experiments/<campaignId>/<runRef>, and report the experiment with setup/session/hypothesis/worker context. onyx research hypothesis add can create another campaign hypothesis at any time from a JSON plan file or inline focus/hypothesis flags; a running supervisor picks up new active hypotheses as soon as worker slots open. Workers publish shared learning with onyx-worker knowledge add and read it back through the session-state brief or fuller research brief, but successor hypothesis selection remains an orchestrator/human decision. After the agent exits, the worker harness performs one final best-effort commit, checks whether HEAD is already represented by a reported experiment, measures/logs exactly one unreported HEAD commit using that commit's parent as the workflow base when the session is still accepting experiments, pushes the immutable experiment ref, reports directly to /api/v1, and pushes the worker branch for recovery. If git push or API reporting fails, the manifest records the pushed/missing refs and retry instructions; it does not create local product state. If the session is already terminal, finalization records discarded_after_completion locally and does not create an experiment, ranking input, result ref, or recovery artifact. Multi-commit, restore-forward, or dirty salvage preserves the branch without producing a measured experiment or blocked workflow run. Worker manifests report finalizationStatus as none, already_logged, measured_and_logged, salvaged_unmeasured, discarded_after_completion, or failed. If onyx research stop is requested while a provider process is still running, the harness gives it the configured stop grace (30 seconds by default), terminates it if needed, then runs the same finalization path. Use --worker-command only for custom harnesses.

Stop and finalize campaigns explicitly:

onyx research stop --session <id>
onyx research finish --campaign fast-eval

finish reads remote state, writes the final campaign summary through /api/v1, marks the remote campaign completed, and prints local extraction branches such as onyx/fast-eval/best.

To delete a research direction entirely — the campaign record with all its experiments and matching local cache rows:

onyx campaign delete --name fast-eval

Deletion is applied directly through /api/v1; the server owns tombstones for deleted campaigns and experiments. Recreating a campaign with the same name later is fine because tombstones only match records created before deletion.

Development

bun install
bun run ci

To make the persistent onyx command use this checkout during development:

onyx developer link .
onyx developer use dev

Developer mode runs source through Bun and replaces the managed Claude, Codex, and OpenCode skill files with symlinks to this checkout's skills/onyx/SKILL.md, so active agents see skill edits from local source. Return to the installed release with:

onyx developer use release

Restart or reload active agent sessions if they cache skill files.

When public CLI commands, flags, profile behavior, local state, sync behavior, or the bundled agent skill changes, update the public docs in /Users/ted/onyx/docs in the same change.

Release binaries are built from Bun standalone executables:

bun run build:release

License

Apache-2.0