セッションとその他の機能

stepper は、レイヤード AI エージェントの動作を拡張・調整するための高度なセッション管理、コンテキスト最適化、ワークフロー制御機能を提供します。

Dispatch ツール

設定で dispatch を有効にすると、モデルが並列のサブエージェントをファンアウトできるようになります。各サブエージェントは独自のコンテキストウィンドウで実行され、その要約が呼び出し元に返されます。ファンアウトの実行中、TUI はリアルタイムの **ワーカーパネル** を表示します（ワーカーごとに 1 行：ステータス、最後のツール、トークン数）。

.stepper/setting.json で設定します:

"dispatch": { "enabled": true }

コンパクション

会話履歴がコンテキストウィンドウの約 70% を超えると、stepper は領域を確保するために以前のメッセージを自動的に畳み込みます。compaction.provider が設定されている場合は、指定された（通常は安価な）モデルが畳み込まれた部分を要約し、設定されていない場合はヒューリスティックなマーカーが使用されます。

コンパクション用モデルを設定します:

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

チェックポイントと巻き戻し

毎ターン、作業ツリーの状態が自動的にスナップショットされます。/rewind コマンドを使うと、以前のスナップショットを復元してその時点でセッションを切り詰められるため、変更を取り消して以前の状態から分岐できます。復元の範囲は /rewind code（ファイルツリーのみ）や /rewind conversation（会話のみ）で絞れ、引数なしの /rewind（および Esc-Esc）は両方を復元します。

セッションと再開

セッション状態は .stepper/sessions/<id>.json に永続化されます。--resume フラグで以前のセッションを再開すると、以前のセッションのコンテキストで新しい実行をシードします:

stepper --resume <session-id>

フック

ライフサイクルフックを設定して、セッションの重要なタイミングでシェルコマンドを実行できます。フックは .stepper/setting.json の hooks キーの下にイベント単位で定義し、一致したペイロードが JSON として stdin に渡されます。終了コードが 0 以外の場合、対応する操作がブロックされます（例：PreToolUse）。ライフサイクルは 9 つのイベントを対象とします:

• SessionStart — セッションの開始時に実行されます
• UserPromptSubmit — プロンプトを送信したときに実行されます
• PreToolUse — ツールが呼び出される前に実行され、0 以外の終了コードはツールをブロックします
• PostToolUse — ツールの完了後に実行されます
• PreCompact — 履歴が畳み込まれる前に実行されます
• SubagentStop — fan-out または dispatch されたサブエージェントの完了時に実行されます
• Notification — 通知イベント時に実行されます
• Stop — ターンが停止したときに実行されます
• SessionEnd — セッションの終了時に実行されます

フック設定の例:

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

インタラプト

実行中のターンで Esc を押すと実行をキャンセルします。これはセッションを終了させることなく、ストリームと処理中のすべてのツール呼び出しを中断し、プロンプトは直ちに次の入力を受け付けられる状態になります。

プロンプトキャッシング

レイヤーごとのシステムプロンプトとツールのプレフィックスは、Anthropic API 呼び出しに対してキャッシュ可能としてマークされるため、ReAct ループ内で繰り返されるリクエストはキャッシュ読み取り料金の恩恵を受けます。OpenAI および Responses 互換プロバイダーは、プレフィックス単位で自動的にキャッシュします。

TUI キーボードショートカット

apply_patch ツール

apply_patch ツールは、構造化された複数ファイルのパッチ（Add / Update / Delete / Move、@@ コンテキストハンクとファジーマッチング付き）をアトミックに適用します。まずすべての変更を検証し、いずれかのハンクが失敗したりゲートが拒否されたりした場合は何も書き込みません。

編集時のフォーマットと LSP

オプトインの format-on-edit は、ファイル編集ツールの実行後に組み込みカタログ（rustfmt、gofmt、prettier、ruff、biome、…）から一致するフォーマッターを実行します。インストール済みの言語サーバーからの LSP 診断は編集後に収集され、ツール結果に追記されます。どちらもデフォルトでは無効で、setting.json の formatter / lsp キーで有効化します。

"formatter": true,
"lsp": true

名前付きサブエージェント

再利用可能なサブエージェントは .stepper/agents/<name>/index.md（モデル、ツール、システムプロンプト）で定義します。呼び出しは task ツールで行うか、プロンプトから #<name> でインラインに呼び出します（型先行ピッカーが一覧を表示します）。各サブエージェントは新しいコンテキストを持つ独自のサブエージェントとして実行され、Task 権限ルールでゲートされます。

Undo / redo

/undo は直前のターンを取り消し、作業ツリーをそのターンの直前のチェックポイントへ復元し、そのターンを破棄します。取り消し前にスナップショットを取るため、/redo で再適用できます（どちらも複数ステップ対応）。新しいターンの開始（または /rewind、/resume、/clear、/compact）はタイムラインを分岐させ、redo スタックを無効化します。

通知

setting.json で notification を設定すると、ターンの完了時、承認待ち時、ターンのエラー時にターミナルベルを鳴らせます。3 つすべてを有効にするには true を、トリガーを選ぶにはオブジェクトを指定します。デフォルトでは無効で、ポータブルなターミナルベルのみ（OS 通知はありません）です。

プロキシとプライベート CA

送信 HTTP は標準の HTTP(S)_PROXY / NO_PROXY 環境変数を尊重します。環境変数を使えない構成では、setting.json に明示的なプロキシ（http / https / all / noProxy / disabled）を設定します。企業 / 自己署名のルートは STEPPER_EXTRA_CA_CERTS（PEM バンドル、システムトラストに追加、fail-open）で追加します。プロバイダー呼び出し、web_fetch、http MCP に適用されます。

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

MCP サーバーの OAuth

OAuth を必要とするリモート（http）MCP サーバーは stepper mcp auth <name>（ブラウザフロー、PKCE、動的クライアント登録）で認可します。トークンは ~/.stepper/mcp-auth.json（0600）に保存され、自動的にリフレッシュされます。stepper mcp logout / status で管理します。サーバーごとに mcpServers の oauth キーで有効化します。

セッション横断の統計

stepper stats は、保存されたすべてのセッションにわたってトークン、コスト、ターン、モデルごと・ツールごとの利用状況を集計します。--days で絞り込み、--models / --tools で内訳を表示し、--json で JSON を出力し、--export（.csv または .json）でファイルに書き出します。ツールごとの内訳は、正規化されたバーと割合を伴う棒グラフで描画されるため、最も負荷の高いツールが一目で分かります。利用状況は今後ターンごとに記録されます。

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

自動メモリ

エージェントは memory_write ツールを呼び出して、永続的な学び — ビルド / テストコマンド、規約、デバッグの知見 — を .stepper/memory/MEMORY.md に追記できます。このファイルは以降のすべてのセッションの開始時にベースコンテキストへ読み込まれ（直近の約 32 KB）、学びが手作業なしにセッションをまたいで引き継がれます。

推論強度

セッションの推論強度は /effort または --effort フラグ（off / low / medium / high / xhigh / max）で設定します。引数なしの /effort は現在のレベルを強調したピッカーを開き、フッターに現在値が表示されます。最新の Claude（Opus ≥ 4.6 / Sonnet ≥ 4.6 / Fable·Mythos 5）ではアダプティブ思考と output_config.effort にマップされ、OpenAI では reasoning_effort（xhigh / max は high にクランプ）に、旧来の Claude ではレガシーな思考バジェット段階にマップされます。

stepper --effort xhigh
# または TUI 内で:  /effort max

外部エディター

/editor を実行（または Ctrl+E を押す）すると、プロンプトを自分のエディターで作成できます — stepper が一時ファイルで $VISUAL / $EDITOR を開き、保存した内容を入力欄に読み込みます。インラインでは入力しづらい、長く複数段落にわたるプロンプトに便利です。

設定の概要

/settings は統合されたタブ表示の概要を開きます — General · Model · Permissions · Theme · MCP · Notifications。← / →（または Tab）でタブを切り替え、Enter でフォーカス中タブのエディター（/permissions、/theme、/model）に直接ジャンプし、Esc で閉じます。

MCP 管理 CLI

setting.json を手で編集することなく、コマンドラインから MCP サーバーを管理できます: stepper mcp list は設定済みサーバーを一覧表示し、stepper mcp get <name> はサーバーに接続してそのツール / リソース / プロンプトを一覧表示し、stepper mcp add <name> は stdio または http サーバーを登録し、stepper mcp remove <name> は削除します。

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

モデル CLI

stepper models [provider] は、選択可能なモデル（各プロバイダーのライブ一覧と models.dev カタログをマージしたもの）をヘッドレスで一覧表示します — デフォルトはプレーンテキスト、スクリプト用には --json、モデルごとのコンテキストウィンドウと価格には --verbose。

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

ヘッドレスのシステムプロンプトオーバーライド

stepper をヘッドレスのリンターやレビュアーとしてラップするために、--system-prompt / --system-prompt-file は実行中のプロジェクトベースコンテキストを置き換え（dispatch されたサブエージェントにも及びます）、--append-system-prompt / --append-system-prompt-file は各レイヤーのシステムメッセージの役割の後に追加の指示を付け足します。

ファイルログ

ログはオプトインです: --log-level を渡すと ~/.stepper/logs/stepper.log に書き込みます（RUST_LOG 環境変数が設定されている場合はそちらが優先されます）。TUI を散らかさずに、ヘッドレス実行や挙動のおかしいプロバイダーをデバッグするのに便利です。

コマンド履歴 & 逆検索

送信したプロンプトは ~/.stepper/history/<project>.json に永続化されます（直近 500 件、連続する重複は除去）。入力の先頭/末尾の行で ↑ / ↓ を押すと、前/次のプロンプトを recall します — 入力中の draft は保存され、末尾に戻ると復元されます。Ctrl+R は部分一致を新しい順でマッチする逆検索オーバーレイを開きます。

fallback モデルチェーン

--fallback-model a,b,c（カンマ区切り）または fallbackModel 設定（文字列または配列）でフォールバックチェーンを指定します。主モデルがリトライ不可の失敗に遭遇するか、リトライを使い切ると、stepper はチェーンのモデルを順に試します。CLI フラグが設定より優先され、各項目は trim・重複除去のうえ最大 3 つに制限されます。

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

統合診断

stepper doctor は一度にすべてをチェックします: 設定の検証、provider API キー、デフォルト/フォールバックモデルの resolve、ライブ MCP サーバー接続、models.dev カタログ、そして GitHub の最新リリースバージョン（ネットワークを含む）。キーの欠落や接続失敗は警告（exit 0）であり、無効な設定や解決不能なデフォルトモデルのみが失敗します。

stepper doctor

structured outputs（ヘッドレス）

ヘッドレスモードでは、-p --output-schema <inline|file> が最終応答を JSON Schema に準拠させます。違反時には検証エラーを含めて再プロンプトし（--output-schema-retries、既定 2）、それでも準拠しなければ non-zero で終了します。検証済みの JSON は再シリアライズされて出力されます（コードフェンス可）。

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

tool-search（ツールの遅延公開）

あるレイヤーのツールが 40 を超え、MCP ツールが存在する場合、stepper は MCP ツール定義をプロンプトから隠し、tool_search メタツールのみを公開します。モデルが検索すると、一致したツールがそのターンの間だけ公開（reveal）されます — ベースコンテキストを軽く保ちつつ、必要なときにすべてのツールに到達できます。

カスタム statusline

setting.json に statusLine: { command: [...] } を設定すると、stepper はそのコマンドをバックグラウンドで定期的に実行し（5s タイムアウト）、モデル / モード / cwd / トークン / コストを JSON で stdin に渡します。その stdout の最初の行がフッターにレンダリングされます — UI をブロックすることはありません。

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

カスタマイズ可能なキーバインド

~/.stepper/keybindings.json（およびプロジェクトの .stepper/keybindings.json）に {"action":"chord"} 形式でバインディングを追加します。バインディングは加算式です — 組み込みのキーは常に動作します。バインド可能: newline、cycle-mode、external-editor、history-search、scroll-up、scroll-down（chord 例: ctrl+t、alt+k）。submit / quit / interrupt はバインド不可です。

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

階層的に累積する CLAUDE.md

プロジェクトルートから現在の作業ディレクトリまで、各サブディレクトリの CLAUDE.md がベースコンテキストに累積されます（最も具体的なものが最後）。これは既存のプロジェクトベース（.stepper/stepper.md などの first-found ファイル）に加算され、既存の動作はそのまま維持されます。

セッションの rename & export

/rename <name> は現在のセッション名を変更して永続化します（stepper session rename <id> <name> でも可能）。/export [path] はセッションの会話を Markdown トランスクリプトに保存し、既定パスは .stepper/exports/<id>.md です。

path-scoped rules

.stepper/rules/*.md に frontmatter の paths: グロブを持つルールファイルを置きます。ルールは現在の作業ディレクトリがそのグロブに一致したときのみベースコンテキストに読み込まれます — ディレクトリ固有の規約が該当する場所でのみ適用されます。

microcompaction

フルのコンパクションが作動する前に、microcompaction は最も古く大きいツール結果だけを折りたたんでコンテキストを回収します — 会話のターンはそのまま保持します。会話を要約せずに余裕を確保します。

ask-user-question ツール

モデルは組み込みの ask_user_question ツールで多肢選択の明確化質問を出せます。TUI はそれを選択オーバーレイとして表示し（数字または ↑ / ↓ + Enter で選択）、選択をモデルに返します。ヘッドレス / UI なしの実行では「未回答」として進行します。