構成

camelCase JSON で stepper を構成します。ユーザーレベルのベース設定にプロジェクト設定がマージされ、プロバイダー、レイヤー、権限、MCP サーバーを扱います。

.stepper/setting.json ファイルは stepper の動作とデフォルト値を構成します。設定は camelCase を使用し、前方互換性があります(未知のキーは無視されます)。ユーザーレベルの ~/.stepper/setting.json がベース構成として機能し、その上にプロジェクト構成がディープマージされます。このとき、オブジェクトはマージされ、配列は置き換えられます。

構成スキーマ

jsonc

{
  "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
}

スキーマ検証

stepper config --schema を実行すると setting.json の完全な JSON Schema が出力されます。stepper config --validate を使用すると、プロジェクト構成をスキーマと照合して検証できます。

主な構成フィールド

mode — 権限モード: auto(プロジェクト内のアクションは実行され、プロジェクト外への書き込みは確認を求めます)、plan(読み取り専用; 編集はブロック)、accept-edits(プロジェクト内の編集は自動承認; 外部の読み取りは確認を求めます)。CLI --mode が優先されます。
defaultModel — デフォルトのモデルプロバイダーと ID(例: anthropic/claude-sonnet-4)。
step — パイプラインを構成するレイヤー名の配列で、順番に実行されます。
providers — kind(anthropic、openai-compat、openai-responses)と接続詳細を含むプロバイダー定義です。オプションの contextWindow は、リストにないモデルのコンテキストゲージを上書きします。
orchestrator — model と temperature を含む orchestrator レイヤーの構成です。
permissions — allow、ask、deny リストを持つグローバル権限ルールです。ルールは Bash(npm run *)、Read(/path)、Write(**)、Mcp(server, tool) のような指定子を使用します。
approvals — 永続化された承認ルール(「常に許可」の決定)の配列です。
mcpServers — MCP サーバー構成です。各サーバーは type(stdio または http)、接続詳細、およびレイヤースコープのフィルタリングをバイパスするオプションの alwaysLoad を指定します。
hooks — ツール実行をインターセプトする PreToolUse などのイベントフックです。
compaction — 履歴の折りたたみ(folding)構成で、折りたたまれた部分を要約する(安価な)provider モデルを指定します。
dispatch — 並列サブエージェントのために、モデルが呼び出せる dispatch ツールを有効にします。