DocsGuides
Agent Mode
Chat with an agent that reads, edits and runs commands in your workspace, following a workflow or as a single agent.
Agent Mode is where most day-to-day work happens. Open it from the left rail. An agent can explore your code, edit files, run commands, search the web and ask you questions, within the permissions you set.
The message box
Type your request in the message box, which says Message agent.... A few things to know:
- Type
@to reference a file, so the agent looks at exactly what you mean. - Use Add Context to attach any file on disk to the prompt, or Folder to attach a folder.
- Choose a skill in the Select skill menu. New chats start with build. See Skills. While the chat follows a workflow, the menu stays on build and reads tools set per step, because each step's profile decides its tools.
- Choose a model in the model picker. If you set up automatic model selection, AUTO appears here too. Reasoning-effort variants of a model are listed separately.
Workflow or single agent
Above the message box, the workflow bar's Mode menu picks how the chat runs:
| Choice | What happens |
|---|---|
| Single agent | One agent loop decides its own path. The bar says Each message runs one agent loop. Good for quick questions and small edits. New chats start here. |
| Stage: … (for example Research & analyze) | A short run, usually read-only, that stops at a written result for you to read. Run the next stage in the same chat and it builds on that result. |
| Workflow: … (for example Plan, build, verify, or one you made) | The chat follows it step by step, unattended, from start to finish. |
| Auto: choose a workflow for each message | Rusty picks the workflow, or the single agent, for each message. Needs OpenRouter and a JEV model. |
When a workflow is selected, its name appears as a chip (click the × on it to stop following the workflow) and its steps are listed in order, for example Request → Plan → Build → Verify → Result. While it runs, the bar tells you where it is: Running step 2 of 4: Build, with (waiting for permission) when a step is blocked on a command prompt, or the attempt number when a step is retrying. When a run ends without finishing, the bar says so, for example Last run cancelled. Your next message runs it again.
The Allow flow switching checkbox lets a running workflow hand over to another. The button at the right of the bar says View workflow for a built-in workflow, or Edit workflow for one of your own, and opens it in Behaviors. The chevron at the left hides or shows the bar.
The workflow's final message is its last step's result, so read it: a finished run means the sequence finished, not that a review approved the change.
Everything about workflows has its own section:
- Workflows: stages and pipelines, running one, and steering a long job between stages.
- Built-in workflows: all 15, step by step.
- Auto flows: letting Rusty choose, and handing over mid-run.
- Profiles & workflows: customizing them and the JSON behind them.
With AUTO selected in the model picker, each workflow step also picks its own model. See Automatic model selection.
What agents can do
Depending on the profile and permissions in force, an agent can use tools such as:
| Tool | Purpose |
|---|---|
read_file, list_files |
Read files and list directories. With smart file reading on, read_file returns only relevant sections. |
search_codebase |
Search your code. Also available as a ranked smart search. |
write_file |
Write complete files. |
run_command |
Run shell commands, after you approve them. See Permissions & safety. |
web_search, web_extract, web_fetch |
Search the web and read pages. Needs a search provider for web_search. |
report_progress |
Tell you how the work is going. |
ask_user_question |
Ask you a question and wait for the answer. |
Agents can also delegate parts of a task to subagents.
Permission prompts
When an agent wants to run a command, Rusty shows Command permission required and waits. You can Deny, Allow once, or allow the program for the rest of the session. Details are in Permissions & safety.
Chat history
Each chat is saved automatically in your workspace, under .rusty/chats/. Use the controls at the top of Agent Mode:
- New chat starts a fresh conversation.
- Show chat history and Hide history toggle the list of past chats.
- Refresh reloads the list.
- Delete chat removes one.
Reviewing what changed
Agents edit the real files in your workspace. Review their work in Source control: open each file's diff, stage what you want to keep, and commit. For larger features where you want changes staged in isolation first, use Rusty Canvas.
Tip
Give the agent a way to check its own work. Mention the test or type-check command in your request, or in the instructions of your Build profile, and the completion gate will hold the agent to it.