Sessions & more

Stepper provides advanced session management, context optimization, and workflow control features to extend and refine layered AI agent behavior.

Dispatch tool

Enable dispatch in configuration to allow the model to fan out parallel sub-agents. Each sub-agent runs in its own context window, and their summaries are returned to the caller. The TUI displays a live **worker panel** (one row per worker: status, last tool, token count) while the fan-out executes.

Configure it in .stepper/setting.json:

"dispatch": { "enabled": true }

Compaction

When conversation history crosses approximately 70% of the context window, stepper automatically folds earlier messages to free space. If compaction.provider is set, a designated (typically cheap) model summarizes the folded part; otherwise, a heuristic marker is used.

Configure a compaction model:

"compaction": { "provider": "anthropic/claude-haiku-4" }

Checkpoint and rewind

Every turn automatically snapshots the working tree state. Use the /rewind command to restore a prior snapshot and truncate the session at that point, allowing you to undo changes and branch from an earlier state. Scope the restore with /rewind code (file tree only) or /rewind conversation (the conversation only); a bare /rewind (and Esc-Esc) restores both.

Sessions and resume

Session state persists to .stepper/sessions/<id>.json. Resume a previous session with the --resume flag, which seeds the new run with the prior session's context:

stepper --resume <session-id>

Hooks

Configure lifecycle hooks to run shell commands at key points in a session. Hooks are defined in .stepper/setting.json under the hooks key, keyed by event, and the matched payload is fed on stdin as JSON. Non-zero exit codes block the corresponding operation (e.g., PreToolUse). The lifecycle covers nine events:

• SessionStart — runs when a session begins
• UserPromptSubmit — runs when you submit a prompt
• PreToolUse — runs before a tool is called; non-zero exit blocks the tool
• PostToolUse — runs after a tool completes
• PreCompact — runs before history is folded
• SubagentStop — runs when a fan-out or dispatched sub-agent finishes
• Notification — runs on a notification event
• Stop — runs when a turn stops
• SessionEnd — runs when a session ends

Example hook configuration:

"hooks": {
  "PreToolUse": [{ "matcher": "write_file", "command": "echo blocked >&2; exit 2" }]
}

Interrupt

Press Esc during a running turn to cancel execution. This aborts the stream and any in-flight tool calls without terminating the session — the prompt is immediately ready for the next input.

Prompt caching

The per-layer system prompt and tools prefix is marked cacheable for Anthropic API calls, so repeated requests in a ReAct loop benefit from cache-read pricing. OpenAI and Responses-compatible providers cache by prefix automatically.

TUI keyboard shortcuts

apply_patch tool

The apply_patch tool applies a structured multi-file patch (Add / Update / Delete / Move, with @@ context hunks and fuzzy matching) atomically — it validates every change first and writes nothing if any hunk fails or a gate is denied.

Format & LSP on edit

Opt-in format-on-edit runs the matching formatter from a built-in catalog (rustfmt, gofmt, prettier, ruff, biome, …) after a file-editing tool; LSP diagnostics from installed language servers are collected after the edit and appended to the tool result. Both are off by default and enabled via the formatter / lsp keys in setting.json.

"formatter": true,
"lsp": true

Named sub-agents

Define reusable sub-agents in .stepper/agents/<name>/index.md (model, tools, system prompt). Invoke one with the task tool, or inline from the prompt with #<name> (a type-ahead picker lists them). Each runs as its own sub-agent with a fresh context, gated by a Task permission rule.

Undo / redo

/undo reverts the last turn — restoring the working tree to the checkpoint just before it and dropping that turn — and snapshots first so /redo can re-apply it (both multi-step). Starting a new turn (or /rewind, /resume, /clear, /compact) forks the timeline and invalidates the redo stack.

Notifications

Set notification in setting.json to ring the terminal bell when a turn completes, an approval is awaited, or a turn errors — true for all three, or an object to pick triggers. Off by default; a portable terminal bell only (no OS notifications).

Proxy & private CA

Outbound HTTP honors the standard HTTP(S)_PROXY / NO_PROXY env vars; for env-less setups set an explicit proxy in setting.json (http / https / all / noProxy / disabled). Add a corporate / self-signed root via STEPPER_EXTRA_CA_CERTS (a PEM bundle, additive to system trust, fail-open). Applies to provider calls, web_fetch, and http MCP.

"proxy": { "https": "http://proxy.corp:3128", "noProxy": "localhost" }

MCP server OAuth

Remote (http) MCP servers that require OAuth are authorized with stepper mcp auth <name> (browser flow, PKCE, dynamic client registration); tokens live in ~/.stepper/mcp-auth.json (0600) and refresh automatically. stepper mcp logout / status manage them. Enable per server with an oauth key in mcpServers.

Cross-session stats

stepper stats aggregates token, cost, turn, per-model and per-tool usage across every saved session. Filter with --days, break down with --models / --tools, emit JSON with --json, or write a file with --export (.csv or .json). The by-tool breakdown renders a bar chart with normalized bars and percentages so the heaviest tools stand out at a glance. Usage is recorded per turn going forward.

stepper stats --models --tools
stepper stats --days 7 --json

Auto memory

The agent can call the memory_write tool to append a durable learning — build/test commands, conventions, debugging insights — to .stepper/memory/MEMORY.md. That file is loaded into the base context (its most-recent ~32 KB) at the start of every future session, so learnings carry across sessions without any manual bookkeeping.

Reasoning effort

Set the reasoning effort for the session with /effort or the --effort flag (off / low / medium / high / xhigh / max); the no-arg /effort opens a picker highlighting the current level, and the footer shows it. Modern Claude (Opus ≥ 4.6 / Sonnet ≥ 4.6 / Fable·Mythos 5) maps it to adaptive thinking plus output_config.effort; OpenAI maps it to reasoning_effort (xhigh / max clamp to high); older Claude keeps a legacy thinking-budget tier.

stepper --effort xhigh
# or in the TUI:  /effort max

External editor

Run /editor (or press Ctrl+E) to compose your prompt in your own editor — stepper opens $VISUAL / $EDITOR on a temp file and loads what you save back into the input. Handy for long, multi-paragraph prompts that are awkward to type inline.

Settings overview

/settings opens a consolidated, tabbed overview — General · Model · Permissions · Theme · MCP · Notifications. Switch tabs with ← / → (or Tab), press Enter to jump straight into the focused tab's editor (/permissions, /theme, /model), and Esc to close.

MCP management CLI

Manage MCP servers from the command line without hand-editing setting.json: stepper mcp list shows the configured servers, stepper mcp get <name> connects to a server and lists its tools / resources / prompts, stepper mcp add <name> registers a stdio or http server, and stepper mcp remove <name> deletes one.

stepper mcp list
stepper mcp get context7
stepper mcp add my-tool --command my-mcp --arg --stdio

Models CLI

stepper models [provider] lists the selectable models (each provider's live list merged with the models.dev catalog) headlessly — plain text by default, --json for scripting, or --verbose for per-model context window and pricing.

stepper models
stepper models anthropic --verbose
stepper models --json

Headless system prompt overrides

For wrapping stepper as a headless linter or reviewer, --system-prompt / --system-prompt-file replace the project base context for the run (reaching dispatched sub-agents too), and --append-system-prompt / --append-system-prompt-file append extra instructions to every layer's system message after its role.

File logging

Logging is opt-in: pass --log-level to write to ~/.stepper/logs/stepper.log (a RUST_LOG env var takes priority when set). Useful for debugging a headless run or a misbehaving provider without cluttering the TUI.

Command history & reverse search

Submitted prompts persist to ~/.stepper/history/<project>.json (last 500, consecutive duplicates dropped). Press ↑ / ↓ at the first / last line of the input to recall earlier / later prompts — your in-progress draft is preserved and restored when you walk back to the end. Ctrl+R opens a reverse-search overlay that matches substrings, most-recent first.

Fallback model chain

Provide a fallback chain with --fallback-model a,b,c (comma-separated) or the fallbackModel setting (a string or array). When the primary model hits a non-retryable failure or exhausts its retries, stepper tries each model in the chain in order. The CLI flag wins over the setting; entries are trimmed, de-duplicated, and capped at three.

stepper --fallback-model anthropic/claude-haiku-4,openai/gpt-5

Integrated diagnostics

stepper doctor checks everything at once: config validation, provider API keys, default / fallback model resolution, live MCP server connections, the models.dev catalog, and the latest GitHub release version (network included). Missing keys or failed connections are warnings (exit 0); only invalid config or an unresolvable default model fail.

stepper doctor

Structured outputs (headless)

In headless mode, -p --output-schema <inline|file> forces the final response to conform to a JSON Schema. On a violation, stepper re-prompts with the validation error included (--output-schema-retries, default 2); if it still does not conform, the run exits non-zero. The validated JSON is re-serialized and printed (a code fence is allowed).

stepper -p "list the open TODOs" --output-schema ./todos.schema.json

Tool search (deferred tool exposure)

When a layer has more than 40 tools and MCP tools are present, stepper hides the MCP tool definitions from the prompt and exposes only a tool_search meta-tool. When the model searches, the matching tools are revealed for that turn — keeping the base context lean while still reaching every tool on demand.

Custom statusline

Set statusLine: { command: [...] } in setting.json and stepper runs that command periodically in the background (5s timeout), feeding model / mode / cwd / tokens / cost as JSON on stdin. The first line of its stdout renders in the footer — without ever blocking the UI.

"statusLine": { "command": ["my-statusline.sh"] }

Custom keybindings

Add bindings in ~/.stepper/keybindings.json (and a project .stepper/keybindings.json) as {"action":"chord"}. Bindings are additive — the built-in keys always keep working. Bindable actions: newline, cycle-mode, external-editor, history-search, scroll-up, scroll-down (chords like ctrl+t, alt+k). Submit / quit / interrupt are not rebindable.

{ "external-editor": "ctrl+t", "history-search": "alt+k" }

Hierarchical CLAUDE.md

From the project root down to the current working directory, each subdirectory's CLAUDE.md is accumulated into the base context (most specific last). This is additive to the existing project base (.stepper/stepper.md and other first-found files), which is unchanged.

Rename & export sessions

/rename <name> renames the current session and persists it (also available as stepper session rename <id> <name>). /export [path] writes the session conversation to a Markdown transcript, defaulting to .stepper/exports/<id>.md.

Path-scoped rules

Drop rule files in .stepper/rules/*.md with a paths: glob in their frontmatter. A rule is loaded into the base context only when the current working directory matches its globs — so directory-specific conventions apply only where they belong.

Microcompaction

Before a full compaction kicks in, microcompaction reclaims context by folding only the oldest, largest tool results — leaving the conversation turns intact. It buys headroom without summarizing the dialogue.

Ask-user-question tool

The model can raise a multiple-choice clarifying question through the built-in ask_user_question tool. The TUI shows it as a selection overlay (pick with a number or ↑ / ↓ + Enter) and returns the choice to the model. In headless / UI-less runs it proceeds as "unanswered".