rune

rune

A minimal terminal coding agent in Go. Inspired by pi-mono.

rune ships with read/write/edit/bash tools, local file search, code indexing and repo maps, read-only git/GitHub inspection, branching sessions with compaction, markdown skills, built-in specialist subagents, optional web tools, and MCP plugin support. It runs against ChatGPT Pro/Plus subscriptions via OAuth, Groq, Ollama, Runpod, and OpenRouter.

Quick start

curl -fsSL https://raw.githubusercontent.com/khang859/rune/main/install.sh | sh

Setup and login

Start rune, then use /providers or /settings to choose and configure a provider:

rune

Provider setup examples:

# Codex: opens a browser to auth via your ChatGPT account
rune login codex

# Groq
export GROQ_API_KEY="..."
rune --provider groq

# Ollama
ollama pull llama3.2
rune --provider ollama --model llama3.2

# Runpod
export RUNPOD_API_KEY="..."
rune --provider runpod --model openai/gpt-oss-120b

# OpenRouter
export OPENROUTER_API_KEY="..."
rune --provider openrouter --model anthropic/claude-sonnet-4.5

API keys can also be stored with /settings.

The installer downloads the latest GitHub release for macOS or Linux and can be rerun later to update rune. Set RUNE_INSTALL_DIR to install somewhere other than ~/.local/bin.

If you have Go 1.26+ installed, you can also install or update from source:

go install github.com/khang859/rune/cmd/rune@latest

Linux source builds may require X11 development headers, such as libx11-dev on Debian/Ubuntu.

Usage

Attachments

Reference files with @path in prompts or press @ / use /files in the TUI to pick files. rune can inline text files and attach supported images and PDFs. See docs/file-attachments-and-pdfs.md and docs/keybindings.md.

Commands

Type / in the editor to see all commands. Highlights:

• /providers — switch provider, e.g. Codex, Groq, Ollama, Runpod, or OpenRouter
• /login — authenticate a provider such as Codex
• /settings — configure providers, API keys, web tools, subagents, and UI options
• /model — switch model for the active provider
• /thinking — toggle thinking display; Ctrl+T also toggles it
• /tree — jump to any point in the session
• /resume — pick a previous session
• /new, /clear, /fork, /clone — manage sessions and branches
• /compact — summarize history
• /plan — enter safe planning mode; edits and bash are disabled, and MCP tools require a read-only allowlist
• /approve — approve a plan and implement it in a new session
• /cancel-plan — clear pending plan state while staying in plan mode
• /skill:<name> — invoke a markdown skill
• /skill-creator — get guided help drafting or improving a rune skill
• /feature-dev — start a guided feature-development workflow with specialist subagents
• /subagents — list built-in and custom subagents
• /mcp — configure MCP servers
• /mcp-status — inspect MCP server/tool status
• /git-status — show repository status
• /files — pick files to attach
• /copy, /copy-mode — copy messages from the transcript
• /repomap — show/toggle the always-on code repo map (status, on, off, budget N)
• /reload — reload custom agents and skills
• /quit — exit

See docs/keybindings.md for the full key map, docs/plan-mode.md for Plan Mode details, docs/feature-dev.md for the feature workflow, and /hotkeys for in-app help.

Customization

• Skills — drop a .md file into ~/.rune/skills/ or ./.rune/skills/. See docs/skills.md.
• Subagents — rune includes built-in specialist subagents and supports custom Markdown agent definitions in ~/.rune/agents/ or ./.rune/agents/. See docs/subagents.md.
• MCP plugins — configure MCP servers with /mcp, the rune mcp CLI, or ~/.rune/mcp.json. See docs/mcp.md.
• Project context — rune walks up from the cwd collecting AGENTS.md.

MCP CLI examples

rune mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "$PWD"
rune mcp add-http context7 --url https://mcp.context7.com/mcp
rune mcp list

Providers

Select a provider with --provider, RUNE_PROVIDER, or /providers in the TUI. Provider-specific models can be selected with --model, /model, or settings. See docs/providers.md.

• Codex — authenticate with rune login codex or /login.
• Groq — set RUNE_GROQ_API_KEY or GROQ_API_KEY, or store the key with /settings.
• Ollama — run a local Ollama server and pull a model, e.g. ollama pull llama3.2. Optional API keys are read from RUNE_OLLAMA_API_KEY or OLLAMA_API_KEY.
• Runpod — set RUNE_RUNPOD_API_KEY or RUNPOD_API_KEY, or store the key with /settings.
• OpenRouter — set RUNE_OPENROUTER_API_KEY or OPENROUTER_API_KEY, or store the key with /settings.

Environment variables

Common user-facing environment variables:

Web tools

rune can optionally expose web tools to the agent:

• web_search — search the web for relevant pages.
• web_fetch — fetch a specific HTTP(S) URL.

web_fetch is available when enabled in settings. web_search requires a configured search provider. For Brave Search or Tavily, set:

export RUNE_BRAVE_SEARCH_API_KEY="..."
# or
export RUNE_TAVILY_API_KEY="tvly-..."
export RUNE_WEB_SEARCH_PROVIDER="tavily"

Or configure it interactively with /settings and paste the key into the masked popup. See docs/web.md for details and security notes.

Development

make all      # vet + fmt check + race tests + build
make test     # race tests
make lint     # staticcheck
make build    # build binary

See docs/architecture.md.

License

MIT.