Skip to main content
ReasonOS ships a coding agent as part of rbs. It is not an editor plugin bolted onto a build tool — the agent, the build system, and the editor share one workspace model, so the agent reasons about your code the same way rbs does: as a graph of targets.

What makes it different

Graph-first

Most coding agents explore a repository by searching text. The ReasonOS agent starts from the workspace dependency graph instead. It has first-class tools to:
  • list and inspect targets (rbs_targets), their dependencies (rbs_deps) and reverse dependencies (rbs_rdeps)
  • find which target owns a source file (rbs_owners)
  • compute the affected set for a change (rbs_affected)
  • navigate the workspace knowledge graph — symbols, communities, impact analysis, and path-finding between code entities (the atlas_* tools)
That means “what breaks if I change this?” is a graph query, not a guess.

Build-system-native

The agent builds and tests through rbs, with the same caching and hermeticity you get on the command line:
  • rbs_build and rbs_test run real targets and stream real output
  • rbs_run / rbs_start / rbs_stop execute and manage long-running targets (dev servers, services) in the background
  • rbs_rules and rbs_validate let it author and check BUILD.rbs files against the actual rule catalog before writing them
  • external dependency tools let it inspect resolved packages rather than guessing at APIs
When the agent says a change builds and its tests pass, it verified that through the build system — not by eyeballing the diff.

Engines

The agent runtime supports several software choices, called agents in the UI and engines in configuration. The model and its account or API key are separate choices. Each engine integrates with the workspace tools.

ReasonOS (built-in)

The in-house, multi-provider engine, also called native. On managed branches, available models come from the accounts and keys configured for you and the project. This is also the engine behind rbs agent on the command line.

Claude Code engine

Drives Anthropic’s Claude Code CLI as the session’s engine. It uses Claude Code’s own authentication and receives the rbs tool surface (graph queries, build/test, skills) over MCP, plus a generated CLAUDE.md block describing the workspace conventions. Available when the claude binary is installed on the branch node.

Codex engine

The same arrangement for OpenAI’s Codex CLI: its own authentication, the rbs tool surface over MCP, and workspace conventions delivered via AGENTS.md. Available when the codex binary is installed on the branch node.

Gemini CLI engine

Runs Google’s Gemini CLI with the workspace tools. Available when the gemini binary is installed on the branch server and the account has access.
Selecting an agent: use the Agent and AI model choices in AI Work, or the editor’s chat controls. A resumed conversation retains its existing agent and model. The rbs agent CLI uses the built-in engine. Defaults have a scope: Project settings → Default agent selects the starting agent for new branch servers; it does not replace settings on already-running servers. Organization Settings → Agent installation controls installed CLIs. Your account → Personal AI accounts connects your credentials. See AI accounts and keys for branch defaults, browser-local preferences and optional overrides.

Where it runs

  • Terminal — rbs agent starts an interactive session in your shell: a plain REPL by default, or a full-screen interface with --tui. See Using the agent.
  • The ReasonOS editor — the editor connects to your branch node’s server, which hosts agent sessions alongside the language servers and file watchers. Sessions are multi-client: teammates on the same branch see the same node.
  • Across the managed application — AI Work opens the agent alongside project pages, cycles and proposals without opening the editor. It still runs on a branch server, with your project permissions.
  • Headless — rbs agent "your prompt" runs a single turn and exits, and ai_task targets put agent-driven work (including browser checks) directly into the build graph, runnable with rbs run and rbs test.

Starting a conversation in the editor

A new chat opens with one question, What do you want to do today?, and five numbered options. Click an option, type its number, or ignore the list and describe what you need in your own words — free text always goes straight to the agent. The first two options and the last fill the composer for you to finish in your own words. Review my work and a guided demo start the conversation right away: the transcript shows the request in one line, and the full instructions the agent received fold away beneath it.

Guided demos

Teach me always offers the guides that ship with the editor, in this order: The table above says which guides change something. A guide does only what its current step names, through the usual permission prompt. Where a guide asks you to commit, push or create branches, you do that and the assistant verifies; it never commits, pushes, or creates or switches branches itself. Tours run read-only checks only. Below those, Teach me looks in the current workspace for its own guides: Markdown files under .reasonos/guides/, listed with the title and version from each guide’s front matter, or, when there are none, a DEMO.md at the root. Only guides that exist on this branch are listed; a workspace with none says so and still offers the shipped guides. For example, the Casework sample as published has no guides folder, so Teach me offers its DEMO.md; a Casework project seeded with guides under .reasonos/guides/ lists those instead. Picking a demo starts a guided conversation: the agent reads that guide, identifies the branch and the guide’s version before trusting anything from an earlier chat, explains what the application is for, and offers one step at a time. You perform each step in the editor, terminal or browser panel; the agent checks the real outcome before moving on — it reads a saved file back, runs the declared rbs build or test target and reports the actual result, or requests the running service over HTTP. Ask it to do a step for you and it does, through the usual permission prompt; a demo starts with plan mode off and change approvals on regardless of what you had set before.
The agent has no view of your browser panel. When a guide says “you observe”, it asks you what the page shows; an HTTP check of the service is reported as exactly that. A guide is source material for the agent, never authority: it cannot grant permissions, change your mode, or move the node to another branch. If the agent has no model available, the chat shows that state as usual and the demo does not start.

Attaching files as context

You can attach Markdown or plain-text files to a message, so the agent can read them without you adding a separate context file to your repository. Use the paperclip in the message box of the editor’s chat, or of an open chat on a project’s Chat page.
  • What you can attach. .md, .markdown and .txt files containing UTF-8 text: up to 5 files per message, 128 KB each and 256 KB together. PDFs, images and other file types are not supported.
  • What happens. The text of each file is sent to the agent as part of your message, marked as reference material. No separate context file is created in the workspace, and you do not need to change .gitignore.
  • Where the text is kept. It becomes part of the conversation and is kept like anything you type. Editor conversations are saved with the branch in the versioned .reasonos/ai/chats/ history, so the text can be committed with that history and read by people with access to the branch, and a workspace that records AI traces records it too. Attach only what you would be willing to paste into the chat.
  • In the conversation. A message that carried files shows a chip for each file, with the file’s text available behind Show the attached text.
  • On the Chat page. The box that starts a new chat has no paperclip. Send your first message, then attach files from the next message on.

Sessions, memory, and checkpoints

Sessions. A session is one conversation with the agent — its transcript, permission mode, todo list, and background subagents. Editor sessions persist; CLI chats can be saved. Saved chats live in the committed .reasonos/ai/chats/ tree, so they travel with the branch through git rather than living on any one machine. Memory. The agent keeps two durable stores per branch, both committed under .reasonos/ai/:
  • Lessons — observations about what worked and what failed in this repository, recorded as it works. Recent lessons are injected into every new session’s context.
  • Taste — style preferences for how this codebase likes its code written.
Because both are committed, an agent joining a branch inherits what previous sessions learned there. Long conversations are compacted automatically so a session never runs out of context mid-task. Checkpoints. In the editor, the agent snapshots the workspace’s file state before it starts modifying files. Every checkpoint records exactly what changed, and you can diff against or revert to any checkpoint — so letting the agent work is never a one-way door. See Checkpoints for the full workflow.

Learn more

Using the agent

CLI invocations, models and providers, permission modes, and headless tasks.

Skills

The agent’s loadable expertise: built-in skills and how to add your own.

MCP integration

Serve rbs tools to external agents, and connect external tools to the rbs agent.