Quickstart

This walkthrough assumes you've installed the CLI and provided a gateway key. Run the commands from the root of a project you want the agent to work on.

Interactive REPL

Run oxagen with no arguments in a terminal to open the interactive session:

oxagen

Type a request and press Enter. The agent reads relevant files, proposes edits, runs commands, and reports back. By default the REPL runs in ask mode: it pauses for your approval before editing a file or running a shell command.

Every action is shown as it happens — tool calls, the agent's streaming answer — and /hud opens a heads-up display of every agent running this session (the current turn, any subagents it dispatched, and background monitors), with elapsed time, model, and cost per agent.

Type / to open the menu of in-session slash commands — set a model, switch permission mode, browse memories, review a diff — or run one of your own. Press Ctrl-C to interrupt a turn, and again to exit.

A simple lookup question ("what's the flag to enable verbose mode?") answers directly, skipping the planner and completeness-judge steps a genuine coding task pays for — the REPL classifies the prompt's intent for free before choosing a path, so a factual question gets a fast answer without losing grounding (the agent still reads relevant files and your knowledge graph).

Copy, paste, and scroll

The REPL uses your terminal's native text selection by default: drag to select, Cmd/Ctrl-C to copy, and it copies clean text — no escape sequences. Keyboard scrolling always works (PageUp/PageDown, Ctrl-U/Ctrl-D, or Up/Down/Home/End on an empty input). If you want the CLI's own mouse handling instead (click-to-position, wheel scroll through the emulator) — which takes over native selection — opt in with /mouse or OXAGEN_CLI_MOUSE=1.

Pasting a single line inserts it in full at any length. Pasting multiple lines collapses to a preview chip (first and last few lines, with a line count) that still sends the full pasted text on submit — so a long paste doesn't flood the input, but nothing is lost.

One-shot runs

Pass a prompt as an argument to run a single task and exit — ideal for scripts, git hooks, and CI:

oxagen "add a unit test for parseConfig covering the empty-input case"

You can also pipe input in:

git diff | oxagen "write a concise commit message for this diff"

One-shot runs are ungated by default (the agent edits and runs commands without prompting), so it can complete unattended. Constrain it with a permission mode when you want a safety rail.

Permission modes

The --mode flag controls what the agent may do without asking:

# Let it edit freely but confirm any shell command:
oxagen --mode auto-edit "refactor the date helpers into a single module"

# Investigate without touching anything:
oxagen --mode readonly "where is rate limiting implemented and is it per-org?"

--readonly is shorthand for --mode readonly.

Choose a model

The agent uses a current Claude Sonnet model by default. Override it per run, per shell, or persistently — models are plain Vercel AI Gateway slugs (vendor/model):

oxagen -m anthropic/claude-opus-4.1 "design a migration plan for the events table"

export OXAGEN_MODEL="anthropic/claude-sonnet-5"   # this shell
oxagen config model anthropic/claude-sonnet-5      # persisted

If the gateway reports a slug as unknown, it has likely drifted — set a current one with oxagen config model <slug>.

-m/--model sets the worker — the model that edits code. The pipeline also uses a separate judge and triage model, each independently configurable; see Per-role models.

Dispatch a fleet

For a larger goal, oxagen agents plans it into tasks and runs several agents in parallel:

oxagen agents "add input validation to every public API route"

• --concurrency <n> — how many agents run at once (default 4).
• Each agent runs in its own git worktree by default and merges the work back, so parallel agents never clobber each other's files. Pass --no-isolate to run them all directly against the working tree instead.
• --readonly — analysis-only fleet (no edits or commands).

oxagen agents --concurrency 6 "migrate components off the deprecated Button API"

For detached, long-lived sessions you can supervise from any terminal, see Fleet. Run oxagen view to audit what agents have done here — recent runs with their model, duration, and real cost, plus code-graph stats and daemon/auth health.

Ground the agent in your knowledge graph

This is what sets oxagen apart from a generic coding agent. If you've authenticated against the platform, pull your workspace knowledge graph into a fast local replica:

oxagen graph pull

The agent now reasons with your graph — entities, relationships, prior decisions — alongside the files in your repo. Query the graph directly any time:

oxagen graph search -q "where do we enforce tenant isolation?" -n 5

See Knowledge graph for the full workflow.

Speed up repeated runs

The context daemon keeps indexes and the code graph warm between invocations, so subsequent turns start faster:

oxagen daemon start
oxagen daemon status
oxagen daemon stop

Review what happened

Inspect exactly how a past turn was handled — prompt, context, model, scores, and the completeness judge's verdict:

oxagen replay --list      # list recent turns
oxagen replay             # replay the latest
oxagen replay 3           # replay the 3rd-most-recent turn

And see what your runs cost, rolled up by model:

oxagen cost --session

Next steps

• In-REPL slash commands — every /command in the interactive session.
• The agent engine — how a turn is planned, executed, and verified.
• Command reference — every command and flag.
• Custom commands, agents & rules — extend the CLI with your own.
• Agent memory and Knowledge graph — the two things the agent grounds on.