Configuration

The .stepper/setting.json file configures stepper's behavior and defaults. Settings use camelCase and are forward-compatible (unknown keys are ignored). A user-level ~/.stepper/setting.json serves as the base configuration; a project's configuration is deep-merged on top, where objects merge and arrays replace.

Configuration Schema

{
  "mode": "auto",                         // auto | plan | accept-edits (CLI --mode wins)
  "defaultModel": "anthropic/claude-sonnet-4",
  "step": ["plan", "implement"],          // the layer pipeline, in order

  "providers": {
    "anthropic": { "kind": "anthropic" },
    "ollama-cloud": { "kind": "openai-compat", "baseUrl": "https://ollama.com/v1" },
    "omlx": {
      "kind": "openai-compat",
      "baseUrl": "http://localhost:8000/v1",
      "contextWindow": 128000             // override ctx% gauge for unlisted models
    },
    "codex": { "kind": "openai-responses", "auth": "codex-oauth" }
  },

  "orchestrator": { "model": "anthropic/claude-sonnet-4", "temperature": 0.2 },

  "permissions": {                        // global rules (deny > ask > allow > mode)
    "allow": ["Read(**)", "Bash(cargo *)"],
    "ask":   ["Write(**)"],
    "deny":  ["Bash(rm -rf *)", "Read(//etc/**)"]  
  },
  "approvals": [{ "rule": "Bash(npm run build)" }],   // persisted "always allow"

  "mcpServers": {
    "context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp", "--api-key", "{env:CONTEXT7_KEY}"],
      "alwaysLoad": true                  // visible to every layer regardless of mcp.allow
    },
    "my-http": {
      "type": "http",
      "url": "https://example/mcp",
      "headers": { "Authorization": "Bearer {env:MY_TOKEN}" }
    }
  },

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

  "compaction": { "provider": "anthropic/claude-haiku-4" },  // model-summarize folded history
  "dispatch":   { "enabled": true }       // expose the model-callable `dispatch` tool
}

Schema Validation

Run stepper config --schema to print the full JSON Schema for setting.json. Use stepper config --validate to validate your project's configuration against the schema.

Key Configuration Fields

• mode — Permission mode: auto (in-project actions run; out-of-project writes prompt), plan (read-only; edits blocked), or accept-edits (in-project edits auto-accepted; outside reads prompt). CLI --mode takes precedence.
• defaultModel — The default model provider and ID (e.g., anthropic/claude-sonnet-4).
• step — Array of layer names forming the pipeline, executed in order.
• providers — Provider definitions with kind (anthropic, openai-compat, openai-responses) and connection details. Optional contextWindow overrides the context gauge for unlisted models.
• orchestrator — Configuration for the orchestrator layer, including model and temperature.
• permissions — Global permission rules with allow, ask, and deny lists. Rules use specifiers like Bash(npm run *), Read(/path), Write(**), and Mcp(server, tool).
• approvals — Array of persisted approval rules ("always allow" decisions).
• mcpServers — MCP server configurations. Each server specifies type (stdio or http), connection details, and optional alwaysLoad to bypass layer-scoped filtering.
• hooks — Event hooks such as PreToolUse that intercept tool execution.
• compaction — Configuration for history folding; specifies a (cheap) provider model to summarize the folded portion.
• dispatch — Enable the model-callable dispatch tool for parallel sub-agents.