Using the Agent - ReasonOS Documentation

Starting a session

Run rbs agent from anywhere inside a workspace:

# 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

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.

Choosing a model

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

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.

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

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.

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 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:

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.

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 already loaded). Editor sessions on the branch node persist across reconnects.

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:

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,
)

rbs test //web/app:qa_login

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

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.

​Starting a session

​Providers and API keys

​Choosing a model

​Permission modes

​Flags

​Slash commands

​Isolating edits with a worktree

​Saving and reviewing sessions

​Delegation and background agents

​Headless agent tasks in the build graph

Starting a session

Providers and API keys

Choosing a model

Permission modes

Flags

Slash commands

Isolating edits with a worktree

Saving and reviewing sessions

Delegation and background agents

Headless agent tasks in the build graph