The agent engine
How one prompt becomes planned, executed, and verified work — the evaluate → enhance → route → execute → judge → revise pipeline, the three model roles, scope-review approvals, and the fast-paths that skip work you don't need.
Every turn — in the REPL, a one-shot run, or a fleet subagent — runs through the agent engine: the same shared pipeline the Oxagen platform runs, so a task behaves the same in your terminal as it does in the app. Understanding its stages explains what /pipeline, /mode, the model-role commands, and scope review actually control.
The pipeline
For a prompt classified as a task, the turn flows through six stages:
evaluate → enhance → route → execute → judge → revise| Stage | What happens | Model role |
|---|---|---|
| Evaluate | A cheap model (or a free local heuristic) scores the prompt's completeness and complexity, proposes context queries, and rewrites it to remove noise. | triage |
| Enhance | Injects grounding — real files and symbols from the code graph, recalled memories, and repo priors. This is the one place both grounding sources feed the turn. | triage |
| Route | The chosen tier picks the cheapest capable worker model. A one-way safety floor escalates auth, billing, security, migration, and architecture prompts to a precise tier — never the other way. | — |
| Execute | The worker runs the local tool loop: read, search the graph, edit files, run commands. | worker |
| Judge | A different model grades the real git diff and command/test output for completeness — a model never grades its own work. | judge |
| Revise | If the judge finds gaps, the worker is sent back with the findings and re-judged, up to a bounded number of rounds. | worker + judge |
Each stage emits an event that drives the live TUI readout, and the whole turn is recorded so you can /replay it. The pipeline degrades gracefully: if an evaluator or judge model fails, it falls back to a heuristic so a turn always completes.
/pipeline off (or --no-pipeline) runs the bare agent — execute only, no evaluate/enhance/judge. Useful when you want a raw model loop with no grounding or verification overhead.
The three model roles
The pipeline uses three distinct models. You can set each independently — see Per-role models for the slash command, settings.json key, and env var for each.
- Worker — the executor. Runs the tool loop and edits code.
- Judge — the completeness advisor. Grades the worker's output; defaults to a model distinct from the worker.
- Triage — the coordinator. Drives planning and the evaluate stage.
Separate from which models run is where they run: /coordinator local moves turns onto an on-device model so no tokens leave your machine.
Planning and fleets
Every REPL turn is planned for real — the triage model decomposes your prompt into a dependency-ordered task list, using a digest of recent conversation so follow-ups ("now do the same for the API") resolve correctly.
- A single-task plan stays in the history-aware main loop.
- A multi-task plan fans out to the fleet: each task runs as its own subagent on the cheapest sufficient model, concurrently, each in its own git worktree, with work merged back.
If planning fails or times out, the engine degrades to a genuine one-task plan — never an invented checklist.
Scope review — plan mode
When settings.confirmScope is on, the REPL pauses after routing, before executing and shows a scope-review overlay: your original prompt, the enhanced prompt the worker will actually run, the routed model and tier, and an estimated cost.
| Key | Action |
|---|---|
Enter / y | Run the turn as shown. |
e | Edit the prompt inline (Ctrl-J for a newline, Esc to cancel the edit). |
Esc / n | Cancel — nothing is executed. |
Ctrl-O | Expand the full enhanced prompt. |
This is the CLI's "plan mode": you see exactly what will run, and what it will cost, before a single file is touched.
Fast-paths — skipping work you don't need
The engine has two independent optimizations so cheap turns stay cheap:
- Simple-prompt classification. A zero-cost heuristic labels each prompt
simpleortask. A lookup question ("what's the flag for verbose mode?") issimple: it keeps evaluate + graph grounding but skips the completeness judge and revise loop when the turn made no file changes. A misclassified "simple" prompt that does edit files still gets judged — the zero-diff guard keeps it safe. - Single-task planner fast-path. A short, single-clause goal maps directly to one task, skipping the planner-model call entirely.
Additional judge-side skips apply to read-only turns with no diff, and to turns where a repro test flipped red→green — executed tests already prove completion, so the judge is skipped.
Tuning a turn
| Knob | Slash / flag | Effect |
|---|---|---|
| Reasoning depth | /effort, --effort | low→max reasoning effort for thinking-capable models. |
| Permission posture | /mode, --mode | ask / auto-edit / bypass / readonly. |
| Cost ceiling | /budget, --budget | Per-turn dollar limit, with grace/prompt/enforce behavior. See Per-turn budget. |
| Grounding + judging | /pipeline, --no-pipeline | Toggle the full pipeline vs the bare agent. |
| Telemetry | /verbose, --verbose | Per-phase timing, tokens, cost, and tool results. |
Related
- Per-role models — set the worker, judge, and triage models.
- Fleet — supervise the subagents a multi-task plan fans out.
- Agent memory and Knowledge graph — the two grounding sources the enhance stage injects.
- In-REPL slash commands — the turn-configuration commands above.
In-REPL slash commands
Every built-in slash command in the interactive REPL — session, model roles, memory, history, and interface — plus how the / typeahead merges built-in, CLI, and custom commands.
Custom commands, agents & rules
Author your own slash commands, named agents, and hard-enforced rules as Markdown files with YAML frontmatter — the $ARGUMENTS templating, discovery order, and worked examples.