Steer

Steer is an AI coding agent.

Features

• Multi-provider — Anthropic (Claude), OpenAI (Codex/GPT), Google (Gemini), xAI (Grok); extended thinking support
• Rich TUI — syntax-highlighted chat, vim editing mode, themeable, terminal notifications
• Headless & server modes — pipe prompts via stdin for scripting/CI; standalone gRPC server for remote/distributed usage
• Built-in tools — grep, ast-grep, file editing, bash, web fetch, sub-agents, and more
• MCP extensibility — connect external tool servers over stdio, TCP, Unix socket, or HTTP
• Sub-agents — dispatch focused child agents for exploration or parallel work, optionally in isolated jj/git worktrees
• Session persistence — resume conversations; SQLite-backed session storage
• Workspace-aware — git and jj (Jujutsu) integration; tracks VCS state per session
• Tool approval system — normal/plan/yolo agent modes; pre-approve tools and bash patterns in config
• Auto-compaction — automatically summarizes context when the window fills up
• Configurable — TOML-based catalogs, session configs, preferences, and custom slash commands
• Auth — API keys, OAuth (ChatGPT/Codex), OS-native keyring storage

https://github.com/user-attachments/assets/5a31ccc9-6a96-4005-ab5a-ae3aa7ae34c4

Install

Shell Script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/BrendanGraham14/steer/releases/latest/download/steer-installer.sh | sh

Cargo

cargo install steer

Quick Start

Simply run steer to start the TUI in a local session.

More options:

❯ steer --help
Command-line interface for Steer coding agent.

Usage: steer [OPTIONS] [COMMAND]

Commands:
  tui          Launch the interactive terminal UI (default)
  preferences  Manage user preferences
  headless     Run in headless mode
  server       Start the gRPC server
  session      Session management commands
  workspace    Workspace management commands
  help         Print this message or the help of the given subcommand(s)

Options:
      --session <SESSION>
          Resume an existing session instead of starting a new one (local or remote modes)
  -d, --directory <DIRECTORY>
          Optional directory to work in
  -m, --model <MODEL>
          Model to use (e.g., 'codex', 'opus', 'sonnet', 'gemini', 'grok', 'openai/custom-model')
      --remote <REMOTE>
          Connect to a remote gRPC server instead of running locally
      --session-config <SESSION_CONFIG>
          Path to session configuration file (TOML format) for new sessions
      --theme <THEME>
          Theme to use for the TUI (falls back to "catppuccin-mocha" when unset)
      --catalog <PATH>
          Additional catalog files to load (repeatable)
  -h, --help
          Print help
  -V, --version
          Print version

Headless mode

# Read prompt from stdin and return a single JSON response
echo "What is 2+2?" | steer headless

# Provide a JSON file containing `Vec<Message>` in the Steer message format
steer headless --messages-json /tmp/messages.json

# Run inside an existing session (keeps history / tool approvals), pipe the prompt from a file
steer headless --session b4e1a7de-2e83-45ad-977c-2c4efdb3d9c6 < prompt.txt

# Supply a custom session configuration (tool approvals, MCP backends, etc.)
steer headless --session-config config.toml < prompt.txt

Authentication

# Launch Steer and follow the first-run setup wizard
steer

# Re-run the wizard any time inside the chat
/auth

Config Files

Steer reads config from two places, the project-level .steer/ directory in your current working directory and the following user-level directory:

Both config directories can contain the same two config files:

• catalog.toml - Defines model providers and models. Steer always includes a built-in catalog, auto-discovers project/user catalogs, and accepts additional --catalog <PATH> files (repeatable). Later catalogs override earlier ones.
• session.toml - Defines defaults for new sessions. Auto-discovery order is project first, then user config, and first existing file wins. Override discovery with --session-config <PATH>.

gRPC server / remote mode

You can supply one or more catalogs with --catalog.

• Server: catalogs passed to steer server are loaded on the server and define available providers/models.
• Local TUI: passing --catalog affects the in-process server started by the CLI.

# Start a standalone server (default 127.0.0.1:50051) with additional catalogs
steer server --port 50051 --catalog ./my-catalog.toml

# Local TUI using a custom catalog (applies to the local in-process server)
steer --catalog ./my-catalog.toml

Sessions

Steer persists data to a session. You may create, list, delete, and resume sessions.

# List saved sessions
steer session list --limit 20

# Delete a session
steer session delete <SESSION_ID> --force

# Create a new session with a config file
steer session create --session-config config.toml

# Resume a session
steer --session <SESSION_ID>

Workspaces

Workspaces track the working directory and VCS state for sessions.

# List all workspaces
steer workspace list

# Show workspace status (VCS info, path, etc.)
steer workspace status --workspace-id <WORKSPACE_ID>
steer workspace status --session-id <SESSION_ID>
# equivalent using the global --session flag
steer --session <SESSION_ID> workspace status

Session Configuration Files

Sessions can be configured using TOML configuration files. This is useful for:

• Consistent project-specific configurations
• Setting up MCP (Model Context Protocol) backends
• Pre-approving tools or bash commands
• Sharing configurations with your team

Note: system_prompt is not supported in session config files. System prompts are configured via agent modes (see Agent Modes).

Example: Minimal Configuration

# session-minimal.toml
[tool_config]
backends = [
  { type = "mcp", server_name = "calculator", transport = { type = "stdio", command = "python", args = ["-m", "mcp_calculator"] }, tool_filter = "all" }
]

Example: Pre-approved Tools

# session-preapproved.toml
[tool_config]
visibility = "all"

[tool_config.approvals]
tools = ["grep", "ls", "read_file", "glob", "read_todos", "write_todos"]

[tool_config.approvals.bash]
patterns = ["git status", "git log*", "npm run*", "cargo build*"]

Example: Full Configuration

# session-full.toml

[workspace]
type = "local"

[tool_config]
backends = [
  { type = "mcp", server_name = "calculator", transport = { type = "stdio", command = "python", args = ["-m", "mcp_calculator"] }, tool_filter = "all" },
  { type = "mcp", server_name = "web-tools", transport = { type = "tcp", host = "127.0.0.1", port = 3000 }, tool_filter = "all" }
]
visibility = "all"

[tool_config.approvals]
tools = ["grep", "ls", "read_file", "glob", "read_todos", "write_todos"]

[tool_config.approvals.bash]
patterns = ["git status", "git diff", "git log*", "npm test", "cargo check"]

[tool_config.approvals.dispatch_agent]
agent_patterns = ["explore"]

[auto_compaction]
enabled = true            # default: true
threshold_percent = 90    # default: 90

[metadata]
project = "my-project"
environment = "development"

Auto-Compaction

Steer automatically compacts conversations when the context window fills up. This is configurable in session config:

[auto_compaction]
enabled = true            # default: true
threshold_percent = 90    # trigger compaction at 90% context usage (default: 90)

MCP Transport Options

Steer supports multiple transport types for connecting to MCP servers:

Stdio

transport = { type = "stdio", command = "python", args = ["-m", "mcp_server"] }

TCP

transport = { type = "tcp", host = "127.0.0.1", port = 3000 }

Unix Socket

transport = { type = "unix", path = "/tmp/mcp.sock" }

HTTP

transport = { type = "http", url = "http://localhost:3000", headers = { "X-API-Key" = "secret" } }

Slash commands (inside the chat UI)

/help           Show help
/auth           Set up authentication for AI providers
/model          Show or change the current model
/agent          Show or switch primary agent mode (normal/plan/yolo) [alias: /mode]
/compact        Summarize the current conversation
/new            Start a new conversation session
/theme          Change or list available themes
/mcp            Show MCP server connection status
/workspace      Show workspace status
/editing-mode   Switch between simple and vim editing modes
/reload-files   Reload file cache

Agent Modes

Steer has three primary agent modes that control tool visibility and approval behavior. Switch modes at any time with /agent (or /mode).

# Show current mode
/agent

# Switch to plan mode
/agent plan

# Switch to yolo mode
/agent yolo

Custom Commands

Define project-specific slash commands in .steer/commands.toml:

[[commands]]
type = "prompt"
name = "review"
description = "Careful and thorough change review"
prompt = """
Review the diff from `jj diff -r main..@` carefully.

1. **Understand the change.** What is this change doing and why?
2. **Architecture & design.** Are there structural problems? Is the high-level approach sound?
3. **Simplification.** Can the design or implementation be simpler?
4. **Correctness & completeness.** Are there bugs, edge cases, or missing pieces?

Be specific — reference files and line numbers.
"""

Custom commands appear as slash commands in the TUI (e.g., /review).

Notifications

Steer supports terminal notifications when certain events occur.

Notification Types

Configuration

Notifications are configured via steer preferences edit:

[ui.notifications]
transport = "auto" # auto | osc9 | off

• transport = "auto" (default) uses OSC 9 terminal notifications.
• In terminals like Ghostty, notification clicks can switch back to the relevant tab.

Authentication

Steer supports multiple methods for providing credentials.

Interactive Setup

The first time you start Steer it should launch a setup wizard. The auth flow can also be triggered via the /auth command.

All providers (Anthropic, OpenAI, Google, xAI) support API key authentication.

Steer also supports authenticating via OAuth for:

• Anthropic — Claude Pro/Max users
• OpenAI — ChatGPT Plus/Pro/Team users (Codex)

Note: If OAuth tokens and an API key are both saved for a provider, the OAuth token takes precedence.

Credentials are stored securely using the OS-native keyring.

Environment Variables

Steer can also load credentials via environment variables. It will detect the following environment variables:

• ANTHROPIC_API_KEY or CLAUDE_API_KEY
• OPENAI_API_KEY
• GOOGLE_API_KEY or GEMINI_API_KEY
• XAI_API_KEY or GROK_API_KEY

Environment variables take precedence over stored credentials.

Tool approval system

Steer provides a set of built-in tools that the AI agent uses to interact with your codebase.

Built-in Tools

Auto-approved by default (no approval prompt in normal mode):

write_todos mutates only the in-session to-do list and is intentionally auto-approved.

Mutating (require approval on first use):

Pre-approving Tools

You can pre-approve specific tools and bash command patterns in your session configuration:

# Pre-approve entire tools by name
[tool_config.approvals]
tools = ["grep", "ls", "read_file", "glob", "read_todos", "write_todos"]

# Pre-approve specific bash commands using glob patterns
[tool_config.approvals.bash]
patterns = [
    "git status",
    "git log*",
    "npm run*",
    "cargo build*"
]

# Pre-approve specific dispatch_agent sub-agents
[tool_config.approvals.dispatch_agent]
agent_patterns = ["explore"]

Preferences

User preferences are stored in ~/.config/steer/preferences.toml (macOS/Linux). Manage them with:

steer preferences show
steer preferences edit
steer preferences reset

Available Preferences

# Default model to use
default_model = "codex"

[ui]
theme = "catppuccin-mocha"
editing_mode = "simple"     # simple | vim
history_limit = 100         # conversation history limit
provider_priority = ["anthropic", "openai", "google", "xai"]

[ui.notifications]
transport = "auto"          # auto | osc9 | off

[tools]
pre_approved = []           # tools to pre-approve globally

[telemetry]
enabled = true

Vim Editing Mode

Steer supports vim keybindings in the input editor. Enable via:

/editing-mode vim

Or set permanently in preferences:

[ui]
editing_mode = "vim"