> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the Agent

> Run the coding agent from the terminal: interactive sessions, one-shot prompts, model selection, permission modes, and headless agent tasks.

## Starting a session

Run `rbs agent` from anywhere inside a workspace:

```bash theme={null}
# Interactive session (plain REPL)
rbs agent

# Full-screen terminal interface
rbs agent --tui

# One-shot: run a single turn and exit
rbs agent "why is //api:server_test failing?"
```

Without arguments, the agent starts an interactive session with inline permission prompts. With a prompt argument it runs one turn headless and exits — nothing prompts, and mutations are denied unless you pass a `--mode` that allows them.

On startup the agent loads the workspace — `WORKSPACE.rbs` and every `BUILD.rbs` — so its graph tools answer from your real target graph, and connects any MCP servers declared in the workspace.

## Providers and API keys

The native engine discovers model providers from your environment:

| Environment variable                  | Provider                  |
| ------------------------------------- | ------------------------- |
| `ANTHROPIC_API_KEY`                   | Anthropic (Claude models) |
| `OPENAI_API_KEY`                      | OpenAI (GPT models)       |
| `GOOGLE_API_KEY` or `GEMINI_API_KEY`  | Google (Gemini models)    |
| `XAI_API_KEY`                         | xAI (Grok models)         |
| `REASONOS_LLM_URL` + `REASONOS_TOKEN` | ReasonOS hosted service   |

<Note>
  Keys come from the environment on purpose — workspace files are committed, and an API key in a committed file is a leaked key. When the hosted service is configured, it also acts as a fallback for models no local provider serves.
</Note>

## Choosing a model

Pass `--model` with a model ID, a short alias, or a `provider/model` reference:

```bash theme={null}
rbs agent --model claude-opus-5        # full model ID (the default)
rbs agent --model sonnet               # alias
rbs agent --model fast                 # alias (Claude Haiku)
rbs agent --model hosted/fast          # provider/model reference
rbs agent --model gpt-5 "review the diff on this branch"
```

Inside a session, `/models` lists every model your configured providers can serve. Useful aliases include `opus`, `sonnet`, `fable`, `haiku`, `fast`, `gpt5`, `gemini`, and `grok`.

For models with controllable reasoning, `--effort low|medium|high|max` sets how hard the model thinks per step.

## Permission modes

The agent asks before doing anything destructive. The session's **mode** sets its default posture toward mutating tools:

| Mode           | Behavior                                                                |
| -------------- | ----------------------------------------------------------------------- |
| `manual`       | Ask before anything that edits files or executes commands. The default. |
| `accept_edits` | Allow file edits without asking; still ask before executing commands.   |
| `auto`         | Allow everything. Never a default — you must choose it.                 |
| `plan`         | Deny every mutation. Investigation only.                                |

```bash theme={null}
rbs agent --mode accept_edits
```

In an interactive session, permission requests appear inline: answer with a numbered option or a bare `y`/`n`. You can allow a tool "for the rest of the session" so you are not asked repeatedly — that consent does not carry over if you later switch to a more permissive mode. Switch modes mid-session with `/mode`:

```
› /mode accept_edits
```

<Warning>
  Headless runs (`rbs agent "prompt"`) have no one to ask, so anything that needs consent is **denied**, not silently allowed. Pass `--mode auto` only when you intend a fully autonomous run.
</Warning>

## Flags

| Flag                | Effect                                                                       |
| ------------------- | ---------------------------------------------------------------------------- |
| `--model <ref>`     | Model ID, alias, or `provider/model` reference                               |
| `--mode <mode>`     | Permission mode: `manual`, `accept_edits`, `auto`, `plan`                    |
| `--effort <level>`  | Reasoning effort: `low`, `medium`, `high`, `max`                             |
| `--max-steps <n>`   | Cap model calls per turn                                                     |
| `--worktree <name>` | Isolate the session's edits in a git worktree                                |
| `--tui`             | Full-screen terminal interface (interactive only)                            |
| `--no-graph`        | Skip loading the build graph                                                 |
| `--no-mcp`          | Skip connecting workspace MCP servers                                        |
| `--print-prompt`    | Print the assembled system prompt and tool definitions with sizes, then exit |

The global `rbs` flags also apply — notably `-e`/`--env` to select the workspace environment and `--workspace-root` to point at a workspace explicitly.

## Slash commands

In the plain REPL:

```
/mode [m]   show or set the permission mode
/todos      show the session task list
/agents     list background subagents
/processes  list background processes the agent started
/models     list available models
/help       show commands
/quit       exit
```

The `--tui` interface supports those plus `/clear`, `/model`, `/tools`, `/skills`, `/skill <name>`, `/status`, `/session`, `/save`, and `/history`. Every loadable [skill](/agents/skills) is also offered as its own slash command — typing `/verification`, for example, asks the agent to load and apply that skill.

## Isolating edits with a worktree

On a branch node several people (and several agents) can share one checkout. To keep an agent's edits out of the shared tree, give the session its own git worktree:

```bash theme={null}
rbs agent --worktree fix-flaky-test
```

The agent edits files in an isolated worktree on its own session branch; merging its work back is an explicit, reviewable step rather than an accident of interleaving.

## Saving and reviewing sessions

In the TUI, `/save` writes the current chat to the committed `.reasonos/ai/chats/` tree and `/history` lists recent saved chats. Because chats are committed, they travel with the branch — a teammate pulling the branch can read what the agent did and why.

<Note>
  The CLI does not resume a saved chat into a live session — each `rbs agent` run starts fresh (with the branch's [lessons and taste memory](/agents/overview#sessions-memory-and-checkpoints) already loaded). Editor sessions on the branch node persist across reconnects.
</Note>

## Delegation and background agents

The agent can fan work out rather than doing everything in one context:

* **`delegate` / `delegate_parallel`** — hand scoped tasks to subagents and wait for their conclusions. Good for large searches and self-contained investigations.
* **Background agents** — `start_agent` launches a named agent that keeps working while the conversation continues; `/agents` lists them, and the session can read from, message, or stop them.

You can define reusable subagent presets in the build language — a name, system prompt, and restricted tool set — with `native.define_subagent(...)` in any loaded `.rbs` module, then request them by name when delegating.

## Headless agent tasks in the build graph

`ai_task` targets make agent-driven work a first-class part of the graph. Declared with `kind = "test"` (the default) they are discoverable by `rbs test`; they can start services first, connect MCP servers, and run the agent through an ordered list of steps in `auto` mode.

The most common form is a browser QA test, using the bundled `ai_qa_test` wrapper — it wires up a Chrome DevTools MCP server so the agent can drive a real browser:

```python theme={null}
load("@rbs//agent/ai_task.rbs", "ai_qa_test")

ai_qa_test(
    name = "qa_login",
    run_targets = [":dev"],           # start the dev server first
    todos = [
        "go to the login page",
        "sign in with the seeded test user",
        "verify the user id is shown in the header",
    ],
    headless = True,                  # set False to watch the browser
    timeout = 300,
)
```

```bash theme={null}
rbs test //web/app:qa_login
```

Under the hood this is the `ai_task` rule, which you can use directly for non-browser tasks:

```python theme={null}
native.ai_task(
    name = "smoke",
    kind = "test",                    # "test" targets run under `rbs test`
    todos = ["build //api:server", "run its unit tests", "report PASS or FAIL"],
    run_targets = [],                 # targets to start in the background
    mcp = [],                         # MCP server names to connect
    model = "",                       # optional model override
    timeout = 300,                    # seconds
)
```

The task passes when the agent completes its steps and reports success; otherwise the target fails like any other test.