stepper is a layered CLI/TUI coding agent. An orchestrator delegates your task through an ordered pipeline of sub-agent layers — each with its own provider, model, and a fresh context window.
curl -fsSL https://stepper.gumyo.net/install-files/install.sh | bashirm https://stepper.gumyo.net/install-files/install.ps1 | iexDetects your OS and architecture, drops the binary on your PATH.
The orchestrator is the base layer. It runs the steps in your setting.json in order, handing each layer’s free-text outcome to the next. Every layer is its own sub-agent — its own model, tools, system prompt, and a fresh context window.
base layer · reads setting.json · routes the pipeline
reads the repo, drafts the approach
edits files with the tools
A layer can fan out — one worker per subtask, each its own context window, joined before the next step.
runs and verifies
Everything is layered, scoped, and fail-closed by default.
Each step is an independent sub-agent with its own model, tools, and system prompt. Sequential by default — mark a layer parallel: true to fan out one worker per subtask. Dispatch a named sub-agent inline with #agent or the task tool.
Anthropic, OpenAI, ollama-cloud, oMLX (local Apple Silicon MLX), and Codex (ChatGPT OAuth). /connect discovers and adds any provider from the models.dev catalog (unsupported entries are shown disabled so a key is never mis-routed); every layer picks its own provider and model, with optional per-model context/pricing overrides.
Full file tools plus apply_patch for multi-file structured edits, opt-in format-on-edit from a built-in formatter catalog, and LSP diagnostics from your installed language servers fed back to the agent after each edit.
auto (the default) runs read-only tools without a prompt anywhere and auto-applies in-project edits, asking only on out-of-project writes; plan and accept-edits round out the modes, on top of allow / ask / deny rules, persisted approvals, and path-scoped rules that load only where they apply. Headless -p is deny-by-default — fail-closed.
A ratatui terminal UI: live markdown on a per-theme coloured panel, a status footer (active layer · model · tokens · ctx% gauge · cost · effort), a diff-approval overlay, command history with Ctrl+R reverse search, an ask-user-question selection overlay, /settings, a /theme editor with 13 built-in palettes, a type-to-filter /models picker, /connect, /effort, /editor (Ctrl+E), /rename · /export, /undo · /redo, and optional terminal-bell notifications. Or run headless with -p, --agent, --file, and --format json.
Session resume, list / delete · /rename · /export and --fork, checkpoint + scoped /rewind (code · conversation), /undo · /redo, automatic context compaction plus microcompaction, a fallback-model chain when the primary fails, auto memory across sessions, nine lifecycle hooks, adjustable reasoning effort, skills with progressive disclosure, slash commands, MCP servers (stdio/http, per-server config + OAuth), and cross-session usage stats via stepper stats.
JSONC setting.json with {env:} / {file:} substitution and STEPPER_CONFIG overrides, hierarchical CLAUDE.md context, custom keybindings and a custom statusline, a stepper doctor integrated check, headless system-prompt overrides and --output-schema structured outputs, a stepper mcp management CLI (list / get / add / remove), an explicit HTTP(S) proxy plus private-CA support, and OAuth for remote MCP servers.
Grab a prebuilt binary — no Rust toolchain required.
macOS / Linux
curl -fsSL https://stepper.gumyo.net/install-files/install.sh | bashWindows
irm https://stepper.gumyo.net/install-files/install.ps1 | iexApple Silicon
aarch64-apple-darwinDirect download.tar.gzx86_64
x86_64-unknown-linux-gnuDirect download.tar.gzx86_64
x86_64-pc-windows-msvcDirect download.zipSTEPPER_INSTALL_DIR~/.local/binWhere the binary is installed.STEPPER_DOWNLOAD_BASE_URLreleases/latest/downloadWhere the archives are hosted.Contributors with a Rust 1.95 toolchain can build directly:
cargo install --path crates/stepper-cliRun stepper in a project and follow the guided setup.
In a project with no .stepper/, stepper runs a short guided setup.
stepperChoose a default model and a permission mode. stepper writes .stepper/setting.json.
stepper config --validateStream one-shot output to stdout and auto-approve in-project actions.
stepper -p "add a README badge" --mode auto{
"defaultModel": "anthropic/claude-sonnet-4",
"mode": "accept-edits",
"step": ["plan", "implement", "test"]
}The layer pipeline, your default model, and per-provider config — camelCase, deep-merged over the user-level base.
Full usage, configuration, providers, layers, permissions, and CI — read it all right here.