Rune Agent

Rune Agent is the AI coding assistant built into Rune. It lives in the same workspace as your code, so it can read and edit files, search and navigate the codebase, run commands, and carry a conversation, all without leaving the editor.

The agent is distributed as the rune-agent package. Install it from Rune's shell with pkg install rune-agent (or run shell pkg install rune-agent from the command prompt).

This page introduces what the agent is and what it can do. More detailed guides will follow in this section.

Two ways to ask

The agent has two entry points, both command prompt commands, depending on how much you need from it:

• Quick question (?): a one-off question about the code you are looking at, answered in a floating window. See below.
• Chat (agent): agent opens a conversation tab. This is the full experience: a back-and-forth dialogue where the agent can use tools, edit files, run code, and work through a task with you. You can pass a saved conversation ID to resume it, and an optional model to use for the session. Without an explicit model, chat uses the default alias (see Models).

Type either at the command prompt. When the editor is in modal mode, the chat input is itself a modal editor, so you get the same motions and text objects you use everywhere else while composing messages.

Quick questions with ?

? <message> asks a one-off question and shows the answer in a floating window, without opening a conversation tab. It is meant to be fast: each ? is its own throwaway session with no saved history.

What the model sees with ?:

• The files you have open. The full contents of every open and focused file are put in context, along with their paths, so you can ask about the code in front of you without copying anything in.
• Your project instructions. Any AGENTS.md guidance for the workspace is applied, so answers respect your conventions.
• The workspace root, for orientation.

It does not receive your cursor position, your selection, or your conversation history. So phrase the question to say what you mean ("what does the retry loop in this file do?") rather than relying on where the cursor is.

? can still use tools when it needs to, so it can read another file or check a reference to answer well. But it is tuned to answer quickly and avoid wandering the codebase. That makes it a good fit for:

• "What does this file (or function) do?"
• "Why might this be failing?"
• "How do I use this API / write this in Go?"
• Quick explanations and one-line fixes you want to read, not apply.

Reach for a full chat instead when you want the agent to make changes across the project, work through a multi-step task, or keep context over a back-and-forth.

By default ? uses the same model as chat. If you prefer a faster or cheaper model for quick questions, point the query alias at one (see Models); whenever that alias is set, ? uses it instead.

Skills

Skills are focused capability bundles the agent can load on demand for a particular kind of work, such as code navigation, understanding, searching, refactoring, or reading diagnostics. The agent pulls in the right skill when your request calls for it.

Skills are also available as slash commands in chat: typing /<skill> (for example /plan, /review, or /commit when those skills are installed) runs that skill directly.

Skill directories

Skills are discovered from a configurable list of directories. By default the agent looks in, in order:

Directory	Scope
.rune/skills	this project
~/.rune/skills	all your projects
.agents/skills	this project
~/.agents/skills	all your projects

The project-local directories let a team ship skills alongside the repository, while the home directories hold skills you want everywhere. Drop a skill into any of these and the agent picks it up.

You manage skills and their directories from the agent shell:

Command	What it does
agent skills list	List the discovered skills.
agent skills show <name>	Show a skill's full instructions.
agent skills list-dirs	List the configured skill directories.
agent skills add-dir <dir>	Add a directory to the search list.
agent skills remove-dir <dir>	Remove a directory from the search list.

Sub-agents and planning

For larger tasks the agent can spawn sub-agents to work in parallel, each scoped to a job. Two come built in:

• explore: a fast, read-only research agent for understanding a codebase without changing anything.
• plan: a read-only architect that designs an implementation plan.

This feeds into plan mode: the agent researches read-only, proposes a step-by-step plan, and waits for your approval before making any changes. If you ask for changes, it revises the plan and presents it again. Once you accept, it executes and shows a live checklist as it goes.

Adding your own sub-agents

explore and plan are just skills. A sub-agent is a skill whose frontmatter sets type: agent, so you can add your own simply by dropping a SKILL.md into one of your skill directories. The agent picks it up automatically and can spawn it by name.

The frontmatter fields that define a sub-agent:

Field	Purpose
name	The agent's ID, used to spawn it.
description	Tells the agent what the sub-agent is for and when to use it.
type: agent	Marks the skill as a spawnable sub-agent.
allowed-tools	The exact set of tools the sub-agent may use. Omitting a tool denies it, which is how explore and plan stay read-only.
parent-context	When true, the sub-agent receives the parent conversation's context.

The body of the file is the sub-agent's system prompt: its instructions, constraints, and style.

For example, a read-only sub-agent that reviews code for a specific concern, placed at .rune/skills/security-review/SKILL.md:

---
name: security-review
description: Read-only reviewer that audits code for security issues such as injection, unsafe input handling, and secrets in source. Reports findings; makes no changes.
type: agent
allowed-tools: read_file search_content find_files find_references search_symbols outline_file describe_symbol
---
You are a security code reviewer. You never modify files or run commands.

Audit the code in scope for:
- Injection (SQL, command, path) and unsafe handling of external input.
- Secrets or credentials committed to source.
- Missing authentication or authorization checks at trust boundaries.

Report each finding with its file, line, and a short explanation. If you
find nothing, say so. Be precise and avoid speculation.

Because its allowed-tools list contains only read and search tools, this sub-agent cannot edit files or run commands, the same way the built-in read-only agents are constrained. Once the file is in place, the main agent can spawn it to run a focused review in parallel with other work.

Memory

We are building a cutting-edge memory system for Rune Agent that lets it carry durable learnings across conversations, such as architecture decisions, project conventions, and prior fixes, and surface them when they are relevant. It is in active development and will land in an upcoming Rune Agent release.

The agent shell

Alongside ? and agent, Rune Agent registers an agent command in Rune's shell for inspecting and managing models, conversations, skills, tools, and configuration. Run agent help to see everything it offers. The most useful subcommands:

Command	What it does
agent models	List available models with their context window sizes.
agent model [<id>]	Show the default model, or a conversation's model.
agent effort [<level>]	Show or set the default reasoning effort.
agent max_tokens [<n>]	Show or set the max output tokens.
agent chats list	List saved conversations.
agent chats show <id>	Show a conversation's history.
agent chats export [--audit] <id>	Export a conversation or its audit log.
agent chats compact <id>	Compact a conversation into a summarized copy.
agent chats fork <id>	Fork a conversation at a chosen message.
agent chats clear <id>	Clear a conversation (its contents are archived).
agent skills ...	Inspect and manage skills (see above).
agent tools	List the tools the agent can use.
agent mcp	Show MCP server status and tool stats.
agent config	Show the current configuration.

Focused chat commands

When you are focused on an open chat tab, use the Rune command prompt's chat commands to act on that conversation:

Command	What it does
chatmodel [<model>]	Show or switch the focused chat's model.
chateffort [<level>]	Show or set the focused chat's reasoning effort.
chatmaxtokens [<n>]	Show or set the focused chat's max output tokens.
chatskill <skill> [args]	Load a skill into the focused chat.
chatclear	Clear the focused chat and archive its previous contents.
chatcompact	Compact the focused chat into a summarized copy.
chatfork	Fork the focused chat at a selected message.
chatexport [--audit]	Export the focused chat or its audit log.
chatlog	Show the focused chat's LLM token audit log.

These are command-prompt commands, not agent shell subcommands and not chat-message slash commands. They are useful when you want completion, history, or key bindings from Rune's normal command surface while operating on the chat you are currently viewing.

Models

The agent works with configurable model providers, including OpenAI, Codex, Anthropic, Claude, Gemini, and local models. You can switch the focused conversation's model or reasoning effort with the chatmodel and chateffort command prompt commands.

Model aliases

Which model the agent uses for each kind of work is controlled by named aliases:

• default: the model new chats use when you do not pass one.
• query: the model ? uses for quick questions.
• compact: the model used to compact (summarize) long conversations.
• dream: the model used for memory consolidation.

An alias is just a name that resolves to a real model, and it works anywhere a model is accepted. You manage aliases with the models alias command from the Rune shell:

Command	What it does
models alias	List the aliases and the models they resolve to.
models alias set <name> <provider/model>	Point an alias at a model.
models alias remove <name>	Clear an alias.

For example, to make chat use Codex's flagship model and route quick questions, compaction, and memory consolidation to smaller, cheaper models:

models alias set default codex/gpt-5.5
models alias set query codex/gpt-5.4-mini
models alias set compact codex/gpt-5.4-mini
models alias set dream codex/gpt-5.4-mini

The models alias <name> <provider/model> shorthand (without set) does the same thing. Run models to see every available provider/model name.

When an alias is unset

default is the one alias to set if you only set one. Any other alias that you leave unset (query, compact, dream) falls back to default, so setting default alone gives every kind of work a sensible model. Set the others only when you want them to differ.

default itself, when unset, resolves to the flagship model of the provider you most recently signed in to. So once you authenticate a provider (see Providers), every alias works out of the box, and signing in to a newer provider moves them over automatically. Set an alias explicitly whenever you want to pin a specific model instead.

Connecting external tools (MCP)

Rune Agent is an MCP (Model Context Protocol) client. Declare external MCP servers in an .mcp.json file and the agent connects to them, discovers their tools, and makes them available in chat, extending what it can do with third-party integrations.

Project instructions

The agent reads AGENTS.md files from your project, walking up from the workspace root, and folds those instructions into how it works. Use them to teach it your conventions, so its output matches your project without repeating yourself each session.ow it works. Use them to teach it your conventions, so its output matches your project without repeating yourself each session.