세션 및 기타 기능

stepper는 레이어드 AI 에이전트의 동작을 확장하고 다듬기 위한 고급 세션 관리, 컨텍스트 최적화, 워크플로 제어 기능을 제공합니다.

Dispatch 도구

설정에서 dispatch를 활성화하면 모델이 병렬 서브에이전트를 팬아웃할 수 있습니다. 각 서브에이전트는 자체 컨텍스트 윈도우에서 실행되며, 그 요약 결과가 호출자에게 반환됩니다. 팬아웃이 실행되는 동안 TUI는 실시간 **워커 패널**을 표시합니다(워커당 한 행: 상태, 마지막 도구, 토큰 수).

.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된 sub-agent가 끝날 때 실행됩니다
• 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

선택형 편집 시 자동 포맷은 파일 편집 도구가 실행된 뒤 기본 제공 카탈로그(rustfmt, gofmt, prettier, ruff, biome, …)에서 일치하는 포매터를 실행합니다. 설치된 language server의 LSP 진단은 편집 후에 수집되어 도구 결과에 덧붙여집니다. 둘 다 기본은 꺼져 있으며 setting.json의 formatter / lsp 키로 활성화합니다.

"formatter": true,
"lsp": true

이름이 지정된 sub-agent

재사용 가능한 sub-agent를 .stepper/agents/<name>/index.md(모델, 도구, 시스템 프롬프트)에 정의합니다. task 도구로 호출하거나, 프롬프트에서 #<name>으로 인라인 호출할 수 있습니다(타입어헤드 피커가 목록을 보여줍니다). 각 sub-agent는 새로운 컨텍스트를 가진 자체 sub-agent로 실행되며, Task 권한 규칙으로 게이팅됩니다.

Undo / Redo

/undo는 마지막 턴을 되돌립니다 — 작업 트리를 그 턴 직전의 체크포인트로 복원하고 해당 턴을 제거합니다 — 그리고 먼저 스냅샷을 떠 두어 /redo로 다시 적용할 수 있게 합니다(둘 다 멀티 스텝). 새 턴을 시작하면(또는 /rewind, /resume, /clear, /compact) 타임라인이 분기되고 redo 스택이 무효화됩니다.

알림

setting.json에 notification을 설정하면 턴이 완료되거나, 승인 대기 중이거나, 턴에서 오류가 났을 때 터미널 벨이 울립니다 — 세 가지 모두에 대해 true로 켜거나, 객체로 트리거를 골라 지정할 수 있습니다. 기본은 꺼져 있으며, 이식성 있는 터미널 벨만 사용합니다(OS 알림 없음).

프록시 & 사설 CA

아웃바운드 HTTP는 표준 HTTP(S)_PROXY / NO_PROXY 환경 변수를 따릅니다. 환경 변수가 없는 환경에서는 setting.json에 프록시를 명시적으로 설정합니다(http / https / all / noProxy / disabled). 기업용 / 자체 서명 루트는 STEPPER_EXTRA_CA_CERTS(PEM 번들, 시스템 신뢰에 추가되며 fail-open)로 추가합니다. provider 호출, 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에 추가할 수 있습니다. 이 파일은 이후 모든 세션이 시작될 때 base 컨텍스트로 로드되어(가장 최근 약 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]는 선택 가능한 모델(각 provider의 라이브 목록과 models.dev 카탈로그를 병합한 것)을 헤드리스로 나열합니다 — 기본은 일반 텍스트, 스크립트용으로는 --json, 모델별 컨텍스트 윈도우와 가격에는 --verbose.

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

헤드리스 시스템 프롬프트 재정의

stepper를 헤드리스 린터나 리뷰어로 감쌀 때, --system-prompt / --system-prompt-file는 실행 동안 프로젝트 base 컨텍스트를 교체하고(dispatch된 sub-agent에도 적용됩니다), --append-system-prompt / --append-system-prompt-file는 각 레이어 시스템 메시지의 역할 뒤에 추가 지시를 덧붙입니다.

파일 로깅

로깅은 선택형입니다: --log-level을 넘기면 ~/.stepper/logs/stepper.log에 기록합니다(RUST_LOG 환경 변수가 설정되어 있으면 그쪽이 우선합니다). TUI를 어지럽히지 않고 헤드리스 실행이나 오작동하는 provider를 디버깅할 때 유용합니다.

명령 히스토리 & 역검색

제출한 프롬프트는 ~/.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)합니다 — base 컨텍스트를 가볍게 유지하면서도 필요할 때 모든 도구에 도달합니다.

커스텀 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가 base 컨텍스트에 누적됩니다(가장 구체적인 것이 마지막). 이는 기존 프로젝트 base(.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: 글롭을 둔 규칙 파일을 배치합니다. 규칙은 현재 작업 디렉터리가 그 글롭에 매칭될 때에만 base 컨텍스트에 로드됩니다 — 디렉터리별 규칙이 해당 위치에서만 적용됩니다.

microcompaction

풀 압축이 작동하기 전에, microcompaction은 가장 오래되고 큰 도구 결과만 접어 컨텍스트를 회수합니다 — 대화 턴은 그대로 보존합니다. 대화를 요약하지 않고도 여유 공간을 확보합니다.

ask-user-question 도구

모델은 내장 ask_user_question 도구로 객관식 명확화 질문을 띄울 수 있습니다. TUI는 이를 선택 오버레이로 표시하며(숫자 또는 ↑ / ↓ + Enter로 선택), 선택을 모델에 반환합니다. 헤드리스 / 무UI 실행에서는 "미응답"으로 진행합니다.