Usage

This guide covers the main workflows a first public release user needs after installing the o4 binary.

Start A Session

Run o4 for the interactive terminal UI. Run o4 --print -p "prompt" for a single non-interactive answer that works in scripts and pipelines.

Set a model explicitly when starting:

o4 -m anthropic:claude-sonnet-4-6
o4 -m gpt-5.5
o4 --print -m gpt-5.4-mini -p "summarize this repository"

If a model ID exists under multiple providers, set default_provider in config so o4 -m <model> resolves to the provider you intend.

default_provider = "openai"
model = "gpt-5.5"

Run A Multi-Agent Task

Multi-agent work runs inside an interactive session through the orchestrator, not a standalone CLI command. Start o4, then kick off a coordinated run with the /campaign command:

/campaign audit the extension surfaces

The orchestrator spawns and coordinates the worker agents; the campaign, team_create, and send_message tools are also available to the agent itself.

Task Contracts

The agent tool (used for Explore/Plan/General/custom sub-agent spawns) accepts an optional field that turns a free-text delegation into a verifiable contract:

• verify: a shell command that must exit 0 before the sub-agent’s final answer is accepted. On failure, the command’s output is fed back to the sub-agent as feedback and it continues (bounded to 2 retries) instead of reporting done without actually passing.

It is optional and off by default. It is most useful for mechanical, verifiable work (“make the ignored tests pass”, “fix the lint errors”) where you want the sub-agent to self-check rather than claim completion on faith.

Sub-agent token usage is reported for visibility and cost accounting, but it never limits or fails the delegated run. Cancellation, bounded turns, and the provider’s context window remain the runtime safety controls.

Provider Authentication

Set one provider key before starting o4:

export ANTHROPIC_API_KEY=...
export OPENAI_API_KEY=...
export GOOGLE_API_KEY=...
export XAI_API_KEY=...

For OpenAI Codex ChatGPT access, use the Codex login flow or export the access token directly:

codex login
o4 -m gpt-5.6-sol

export OPENAI_CODEX_ACCESS_TOKEN=...
o4 -m gpt-5.6-sol

For Claude Code OAuth access to Anthropic models, use the separate claude-code provider. Export the token directly or import it from Claude Code after logging in:

export CLAUDE_CODE_OAUTH_TOKEN=...
o4 -m claude-code:claude-sonnet-4-6

claude login
/auth import claude

Use /config in the TUI to inspect provider settings, stored API keys, router setup/status, and custom OpenAI-compatible providers. /config > Providers starts with router setup and router status; choose Add custom provider when you need to add a custom compatible endpoint, then select that provider from the same Providers tab.

BYOK Smart Router

If you configure more than one provider or provider account, open /config > Providers and choose router setup to enable reliability fallback. The router keeps a session on one model and only switches to an eligible fallback route after retryable provider errors such as rate limits, overloads, timeouts, or server errors.

Use the router status row in /config > Providers or run /router status to inspect the active primary model, usable fallbacks, skipped candidates, route-diversity warnings, and provider capacity caps.

See BYOK Smart Router for setup, TOML examples, context-window behavior, and troubleshooting.

Slash Commands

Type / in the input box to open command completion. Common commands:

Command	Use
/help	Show available commands and keybindings
/config	Open settings for model, providers/keys, reasoning, permissions, themes, keybindings, MCP, plugins, agents, skills, tools, LSP, and formatters
/context	Inspect context-window and token usage
/cost	Inspect token/cost totals
/tasks	Show tracked background tasks
/todo	Open the editable session todo list
/todo add <text>	Add a user-owned todo and notify the active model
/campaign <objective>	Start a validated multi-agent campaign
/agents	Open the agent browser
/skills	Open the skill browser
/resume [id]	Open the session browser or resume a saved session
/plugins	Open the plugin browser
/mcp	Open the MCP browser

Keybindings

Frequently-cycled settings have dedicated chords, so you never need to open /config mid-flow:

Key	Action
Alt+R	Cycle reasoning effort (off → low → … → top tier → off)
Alt+A	Cycle approval policy (Ask → Accept edits → Read only → Don’t ask)
Shift+Tab	Toggle plan mode
Alt+N / Alt+W	New / close session tab
Alt+L	Open or close the session todo list

All of these are remappable from [keybindings] in .o4/config.toml:

[keybindings]
cycle_reasoning  = "alt-r"      # alt-<char>, shift-tab, or f1..f12
cycle_approval   = "shift-tab"  # rebinding a used chord replaces the default
toggle_plan_mode = "f2"
new_tab          = "alt-n"
close_tab        = "alt-w"
toggle_todo_list = "alt-l"

Ctrl chords are reserved for built-in shortcuts and cannot be remapped. Invalid entries are reported as a warning toast at startup and the default binding is kept.

Tools And Permissions

The model can request tools such as bash, read, write, edit, grep, glob, fetch, web_search, agent, and task tools. o4 asks before running tools that need approval unless config rules already allow them.

Example permission rule:

[[permissions.rules]]
pattern = "Bash(cargo test*)"
action = "allow"

Use stricter rules for public or shared machines. Keep secrets out of prompts and repository files.

Supply-Chain Gate

Before running an npm/pnpm/yarn/bun install|add, cargo add, pip install/uv add, or go get command, o4 audits each named package:

• Typosquat check — blocks names one or two edits away from a well-known package (e.g. lodahs vs lodash)
• Known advisories — queries OSV.dev and warns on any matching vulnerability

A clean install is silent. A flagged one shows a verdict card; typosquats block the command outright, advisory hits warn but let it proceed. Results are cached in .o4/cache/supply-chain.json so repeat installs in a session don’t re-query the network. An unreachable registry degrades to a silent pass rather than blocking your workflow offline.

MCP Servers

MCP servers expose external tools to the model. In the TUI, use /mcp to open the unified MCP browser. The browser starts on configured servers and includes rows for adding a server, searching the registry, restarting servers, viewing details, toggling configured servers, and removing servers.

For scripting or non-interactive setup, use the CLI shortcuts:

o4 mcp list
o4 mcp search filesystem
o4 mcp add <name> --global
o4 mcp restart <name>

Plugins

Project plugins live under .o4/plugins/<name>/; global plugins live under ~/.o4/plugins/<name>/. o4-native plugins use .o4-plugin/plugin.json and can contribute slash commands, agents, skills, workflow metadata, and skill hooks.

In the TUI, use /plugins to open the plugin browser. On its first open, the browser starts on Installed when plugins are present and Discover otherwise; later opens restore the last tab and filter. It includes rows for installing from Git, viewing details, updating, validating, removing, and inspecting load errors.

For scripting or direct actions, use the plugin command shortcuts:

/plugins
/plugins validate <name>
/plugins install <git-url> --project

See docs/o4-plugins.md for manifest and file layout details.

Agents

Agents can come from built-ins, project-local .o4/agents, user ~/.o4/agents, and installed plugins. In the TUI, use /agents to open the agent browser. The browser starts on the agent list and includes tabs for all, project, user, built-in, plugin, and load-error entries.

The first row creates a new project or user markdown agent. Agent detail rows let you select an agent for the next task, edit or delete editable definitions, and view the loaded definition. Direct shortcuts such as /agents create <name>, /agents select <name>, /agents edit <name>, and /agents delete <name> open the same browser flows.

Skills

Skills can come from project-local .o4/skills, user ~/.o4/skills, and installed plugins. In the TUI, use /skills to open the skill browser. The browser starts on the skill list and includes tabs for all, project, user, plugin, and load-error entries.

The first row creates a new project or user SKILL.md. Skill detail rows let you select a skill for the next task, edit or delete editable definitions, and view the loaded definition. Direct shortcuts such as /skills create <name>, /skills select <name>, /skills edit <name>, and /skills delete <name> open the same browser flows.

Sessions And Recovery

Use o4 sessions list to find saved sessions and o4 --session <id> to resume. Inside the TUI, /resume opens the session browser and /resume <id> resumes a specific saved session. The footer shows model, mode, cost, and context usage so long-running work is easier to monitor.

Release Checks

Before publishing a tag, run:

scripts/release-check.sh

This verifies formatting, whitespace, version bumps, secret scanning, workspace check/test, release build, and a deterministic local model smoke test against open4rena-smoke:open4rena-usage-smoke. Set O4_RELEASE_SMOKE_MODEL=<model-id> or O4_RELEASE_MULTI_AGENT_SMOKE_MODEL=<model-id> to add real provider smokes. For Claude Code OAuth, set CLAUDE_CODE_OAUTH_TOKEN and use claude-code:claude-sonnet-4-6 as the smoke model.