claude-supertool: Claude Code 비용을 50% 절감하는 도구

Claude Code 비용을 50% 절감하세요. git-status를 사용하되, 다음에 무엇을 해야 할지 알려줍니다.

토큰을 절약합니다. 비용을 절약합니다. 턴 (Turns)을 절약합니다. 대화형 세션 (Interactive sessions)과 자율 실행 (Autonomous runs) 모두에서 동일하게 작동합니다. Kevin 스타일의 헤드리스 에이전트 (Headless agents)뿐만 아니라, Claude Code와 페어 프로그래밍 (Pair-programming)을 하는 사람들도 매일 사용합니다. 단 하나의 Python 파일, 의존성 (Deps) 없음, Python 3.9+ 지원.

왜 사용하는가 • 네 가지 기둥 • 영수증 (Receipt) • 배치 처리 (Batching) • 병렬 처리 (Parallel) • 입력 양식 (Input forms) • 검증기 (Validators) • 확장하기 • 설치

# 7개 작업, 1번의 왕복 (Round-trip), 안전한 경우 병렬 처리
supertool 'read:src/Module.py' 'read:src/Auth.py' 'grep:TODO:src/:20' 'map:src/'

2026년의 망치 (Hammer). Claude Code의 기본 도구 벨트 (Toolbelt)는 1995년식 Unix와 같습니다: cat은 파일 하나, grep은 패턴 하나, git status는 200바이트의 Porcelain 데이터를 반환할 뿐입니다. 모든 도구 호출 (Tool call)은 시스템 프롬프트 (System prompt), CLAUDE.md, 규칙, 이전의 모든 턴을 포함한 전체 대화 캐시 (Conversation cache)를 입력 가격의 10%로 다시 전송합니다. 파일 7개를 읽나요? 그 접두사 (Prefix) 비용을 7번 지불해야 합니다. git status를 실행한 후 ahead/behind 정보도 필요했다는 것을 깨달았나요? 단 한 번의 결정을 위해 비용을 두 번 지불하세요. 청구 금액은 턴이 거듭될수록 복리로 쌓입니다.

2026년의 드릴 (Drill). supertool은 다음 질문을 현재 호출에 포함하는 에이전트용 변형 (Variants)을 제공합니다:

— 브랜치 (Branch) + 트래킹 (Tracking) + ahead/behind + 수정된 파일 (Dirty files) + 열린 MR/PR + 제안된 다음 단계. 단 한 번의 호출로 결정 준비 완료. git-status / gl-mr:NUMBER

— 전체 MR/PR 대시보드: 브랜치, 파이프라인 (Pipeline), 리뷰어 (Reviewer), 승인 (Approval), diff 통계, 댓글. 4~5번의 gh-pr:NUMBER glab / gh 호출을 대체합니다.

— 모델, 소요 시간 (Duration), 도구 호출 (Tool calls), 토큰 (Tokens), 캐시 히트율 (Cache hit %), 도구별 오류 (Errors-by-tool). 자신의 실행 내역을 감사(Audit)하세요. claude-log-summary:UUID

이것은 샘플일 뿐입니다. supertool은 약 40개의 작업 (Built-ins + gitlab / github / git / claude-log 프리셋)을 즉시 제공하며, 자신만의 작업을 추가하면 빠르게 60개를 넘어설 수 있습니다.

변형 (Variant)이 바로 레버리지 (Lever)입니다. 절약된 한 번의 턴은 단순히 자유 시간이 아니라, 다시 지불하지 않아도 되는 캐시된 접두사 (Cached prefix)입니다.

기둥 (Pillar)	기능
올바른 도구 (Right tool)	변형(Variants)이 상태(state) + 가드(guards) + 다음 단계(next-step)를 하나의 호출로 묶습니다. 기억해야 할 것이 줄어듭니다.
배치 (Batched)	7개의 작업(ops)을 1번의 왕복(round-trip)으로 처리합니다. 캐시된 접두사(Cached prefix)를 7번이 아닌 단 한 번만 다시 지불하면 됩니다.
병렬 (Parallel)	배치 내의 읽기 전용 작업(Read-only ops)은 동시에 실행됩니다. 콜드 I/O (cold I/O) 환경에서 약 3~5배 더 빠릅니다.
확장 가능 (Expandable)	단 4줄의 JSON으로 커스텀 작업(custom op)을 추가할 수 있습니다. 프리셋(Presets)으로 gitlab, github, git, claude-log가 제공됩니다.

모드 (Mode)	캐시 읽기 (Cache reads)	출력 (Output)	턴 (Turns)	절감액 (Savings)
Hammer (배치 미사용)	436K	1,400	10	—
...

토큰은 50% 적게, 실제 소요 시간(wall time)은 3~4배 더 빠르게. 턴(turns)이 줄어들면 접두사 재읽기(prefix re-reads)도 줄어듭니다. 이를 작업 수와 팀 규모에 곱해보면, 비용 절감 효과는 실질적입니다.

가공되지 않은 셸(raw shell) 대신 변형(variants)을 사용하면 세 가지 변화가 일어납니다:

1. 자신만의 작업(ops)을 구축합니다. Digital Process Tools는 그 위에 스택을 구축했습니다. supertool과 함께 제공되는 것은 없지만, 모두 5~15줄의 JSON으로 작성되었습니다: git-commit (stage + commit + receipt), mr (push + MR + reviewer), mysql_read / mysql_write

이것은 플러그인의 hooks/hooks.json을 통해 세션 시작 훅(session-start hook)을 자동 등록합니다.

— 수동으로 settings.json 편집할 필요 없음.

또는 직접 — 레포지토리를 클론하고 supertool.py를 $PATH에 supertool로 심볼릭 링크(symlink)합니다.

git clone https://github.com/Digital-Process-Tools/claude-supertool.git
ln -s "$(pwd)/claude-supertool/supertool.py" /usr/local/bin/supertool
chmod +x /usr/local/bin/supertool

확인:

supertool 'read:README.md'

독립적인 설치는 세션 시작 훅을 연결하지 않습니다(플러그인 시스템 없음). 바이너리만 얻게 되며, 마켓플레이스 설치를 하면 프로젝트의 작업(ops)에 모델이 적응할 수 있도록 세션 시작 프롬프트가 추가됩니다.

설치하기만 하면 됩니다. 세션 시작 훅은 .supertool.json에서 프로젝트별 작업 참조를 출력하기 위해 ./supertool 'introduction' 'output-format' 'ops-compact'를 실행합니다. 모델은 무엇이 사용 가능한지, 그리고 어떻게 배치(batch)할 수 있는지 학습합니다. 이보다 더 나은 경우 네이티브 Grep/Read로 폴백(fallback)됩니다.

주의 — 훅 출력 용량 제한. Claude Code는 훅의 표준 출력(stdout)을 약 7KB 근처에서 잘라냅니다. 그 이상일 경우, 모델에 도달하는 것은 약 2KB 미리보기뿐이며 나머지는 디스크에 조용히 저장됩니다. 작업이 많은 경우, 목록의 후반부는 작업을 진행하다가 다시 발견될 때까지 숨겨질 수 있습니다. 세션 시작 훅은 용량 제한을 준수하기 위해 ops-compact를 사용합니다: 예시는 자명한 작업(self-explanatory ops)에서는 생략되고, .supertool.json에서 `

CLI 플래그 (claude -p bypass mode):

claude -p "..." --permission-mode bypassPermissions \
--disallowedTools "Grep,Glob,LS,Bash(find:*),Bash(cat:*),Bash(grep:*),Bash(ls:*),Bash(sed:*),Bash(awk:*),Bash(tail:*),Bash(head:*)"

--allowedTools는 bypass mode에서 무시됩니다 — bypass를 사용할 때는 항상 --disallowedTools를 사용하세요.

읽기(reads), 검색(search), 편집(edits), 심볼 매핑(symbol mapping) 및 메타(meta)에 걸쳐 약 40개의 연산(ops)이 존재합니다. 전체 참조는 카테고리별 페이지와 전용 map 심층 분석(deep-dive)을 포함하여 docs/operations/index.md에 있습니다.

빠른 예시:

./supertool 'read:src/Foo.py' 'grep:TODO:src/' 'map:src/'

인자를 전달하는 세 가지 방법이 있습니다. 전체 참조: docs/input-forms.md.

Colon-CLI (기본값) — read:PATH:OFFSET:LIMIT

콘텐츠에 콜론(:)이 포함된 경우 :::를 사용합니다: edit:::OLD:::NEW:::PATH.

@file을 위한 JSON 페이로드 — edit / replace_lines / paste / vim 라우트용. 콘텐츠가 여러 줄이거나 셸(shell) 환경에서 문제가 될 수 있는 경우: edit:@.max/my-edit.json.

한 번의 왕복(round-trip)으로 읽기와 쓰기를 혼합: batch:@file 또는 batch:@.max/ops.json (순수 배열 또는 {continue_on_error, ops} 래퍼).

모든 변경 연산(mutating op: edit, replace, replace_lines, paste, vim)은 결과에 대해 일치하는 검증기(validators)를 실행합니다. 구문 오류(Syntax fail) 발생 시 → 원자적 롤백(atomic rollback)이 수행됩니다. 모델은 즉각적인 오류 영수증(error receipt)을 받고 깔끔하게 재시도합니다.

예시: 쉼표가 누락된 .json 파일을 편집 → jsonlint가 이를 감지 → 파일이 복구됨 → 영수증에 줄/열 정보와 함께 파싱 오류가 표시됨.

17개의 검증기가 기본으로 포함되어 있습니다 (PHP, XML, JSON, YAML, INI, Python, Bash, JS, TS, SCSS, Markdown, Ruby, Dockerfile, Go, Terraform, Rust, TOML). 툴체인(toolchain)이 없는 경우 유연하게 건너뜁니다.

전체 참조: docs/validators.md — 포함된 목록, 연결 방식, 사용자 정의 검증기 추가 방법.

포맷터(Formatters)는 모든 편집 후, 검증 전 단계에서 실행됩니다 — 편집(edit) → 포맷팅(format) → 검증(validate) → 검증 실패 시 롤백(rollback if validate fails).
포맷터는 파일을 제자리에서 변경(prettier --write, gofmt -w)하므로 검증기는 항상 정형화된(canonical) 출력을 보게 됩니다.

prettier가 첫 번째로 포함된 포맷터로 제공됩니다. rollback_on_fail의 기본값은 false입니다.

— 포맷터 (formatters)는 미적인 요소이며, 검증기 (validator)가 안전망 역할을 합니다.

전체 참조: docs/formatters.md — 설정 형태 (config shape), 번들로 제공되는 포맷터 (bundled formatters), 사용자 정의 포맷터 추가 (gofmt, black, rustfmt, phpcbf).

Supertool은 별도의 설정 없이도 작동합니다. .supertool.json은 선택 사항입니다. 이 파일은 ./supertool 'introduction' 'ops'를 통해 LLM 온보딩을 위한 자기 문서화 작업 (self-documenting ops)을 활성화합니다.

프로젝트 루트에 파일을 생성하세요. supertool은 현재 작업 디렉토리 (cwd)에서부터 상위로 올라가며 파일을 찾습니다. 시작 템플릿은 .supertool.example.json 형태로 제공됩니다.

전체 참조 (섹션, builtin-ops 재정의, 사용자 정의 작업 (custom ops), 별칭 (aliases), 디스패치 순서 (dispatch order), 플레이스홀더 (placeholders), 환경 변수 (env vars)): docs/configuration.md.

8개의 프리셋 (presets)이 기본으로 제공됩니다 (git, github, gitlab, claude-log, hashnode, devto, bluesky, xml). 각 프리셋은 docs/presets/에 전용 참조 페이지가 있으며, 작업 (ops), 일반적인 워크플로우 (workflows), 환경 변수 (env vars), 작성 노트 (authoring notes)를 다룹니다.

직접 작성하기: docs/contributing.md를 참조하세요.

check:PRESET:PATH 작업은 여전히 작동합니다. 이 작업은 먼저 ops 섹션을 읽고, 하위 호환성을 위해 .supertool-checks.json을 참조합니다. 새로운 프로젝트에서는 check:mypy:file 대신 직접적인 작업 (mypy:file)을 사용해야 합니다.

휴리스틱 grep (Heuristic grep)은 빠르지만 부정확할 수 있습니다. 실제 언어 서버 (Language Server; intelephense, pyright, typescript-language-server, gopls, rust-analyzer)는 모든 심볼 (symbol)이 어디에 정의되어 있는지 알고 있지만, CLI 호출마다 서버를 실행하면 매번 5~60초의 콜드 인덱싱 (cold-index) 비용이 발생합니다.

Supertool은 mcp 프리셋을 통해 장기 실행되는 **MCP 데몬 (MCP daemon)**을 제공합니다. 이 데몬은 하나의 MCP 서버 서브프로세스 (일반적으로 LSP를 래핑한 cclsp)를 소유하며, supertool 호출 간에도 활성 상태를 유지합니다. 또한 Unix 소켓을 통해 밀리초 단위로 resolve / refs / workspace 요청에 응답합니다.

# 1. LSP + MCP↔LSP 브릿지 설치
npm install -g intelephense cclsp
# 2. cclsp를 LSP로 지정
...

프리셋에서 제공하는 작업 (Ops): mcp_daemon, mcp_status, mcp_stop, mcp_stop_all.

연결된 LSP 기반 작업: resolve, refs, diag, hover, rename, 그리고 workspace 내부의 섹션별 LSP 라우팅 (LSP routing).

전체 참조 (아키텍처, 5가지 LSP 연산, 새로운 MCP 서버/언어 추가 레시피, 도구 이름 참조, 문제 해결): docs/mcp-integration.md.

Notifier(알림기)는 Validator(검증기)의 읽기 친화적인 형제 격입니다. 동일한 hooks_into / match 구조를 가지지만, spawn-and-forget (실행 후 방치) 방식입니다. 즉, 쓰기(write)뿐만 아니라 읽기(read) 시에도 실행되며, 부모 연산(parent op)을 절대 차단하지 않고 롤백(rollback) 의미론도 없습니다. 이들은 외부 도구가 supertool의 연산 스트림(op stream)에 접속할 수 있도록 존재합니다: 에디터 동기화, Slack 알림, 감사 로그(audit logs) 등 무엇이든 가능합니다.

"notifiers": {
"my-observer": {
"cmd": "python3 observe.py {op} {file} {line} {line_end} {before_file}",
...

Placeholder(치환자): {op}, {file}, {line}, {line_end}, {before_file} (변이 연산(mutating ops)을 위한 편집 전 콘텐츠 경로), {supertool_dir}. 설정되지 않은 값은 빈 문자열로 렌더링됩니다.

전체 참조: docs/notifiers.md.

가장 대표적인 Notifier 소비자입니다. VSCode/Cursor 확장 프로그램이 Unix 소켓(Unix socket)에서 대기하며, supertool은 연산당 하나의 JSON 이벤트를 기록합니다. 에이전트가 파일을 **편집(edit)**하면, Cursor는 이를 측면 diff view (차이 보기)(편집 전 vs 편집 후)로 엽니다. 에이전트가 특정 범위를 읽으면(read), 해당 라인들이 파란색으로 강조되고 에디터가 중앙으로 스크롤되며, 강조 효과는 4초 후에 사라집니다. 상태 표시줄(Status bar)에는 연산 유형 아이콘과 함께 최근 연산이 표시됩니다.

자율 에이전트와 페어 프로그래밍(pair-programming)을 하는 것과 가장 유사한 경험입니다. 추가 명령 없이도 에이전트의 작업이 발생하는 즉시 에디터에서 시각적으로 확인할 수 있습니다.

단일 스크립트:

bash notifiers/cursor-witness/install.sh # Cursor (기본값)
bash notifiers/cursor-witness/install.sh --vscode # VSCode도 지원

이 스크립트는 Node ≥18 여부를 확인하고, TypeScript 확장 프로그램을 컴파일하며, 이를 에디터의 확장 프로그램 디렉토리에 심볼릭 링크(symlink)로 연결한 뒤, 프로젝트의 .supertool.json Notifier 블록에 붙여넣을 수 있는 JSON 스니펫을 출력합니다. 에디터를 재로드(Cmd+Shift+P → Developer: Reload Window)하면 상태 표시줄에 $(eye) Max: idle이 표시되어야 합니다.

supertool 자체의 .supertool.json

이미 커서-위트니스(cursor-witness)가 연결되어 있어 supertool 소스 코드의 모든 수정 사항이 에이전트를 로컬에서 실행하는 사용자에게 Cursor에 표시됩니다. 가장 간단한 도그푸드 신호입니다.

만약 에이전트가 op를 발생시키지만 Cursor가 반응하지 않는 경우, 알림기(notifier) 디버그 로거를 활성화하세요:

SUPERTOOL_NOTIFIER_DEBUG=1 ./supertool 'edit:::OLD:::NEW:::FILE'
tail -f /tmp/supertool-notifier-debug.log

또는 지속적인 추적을 위해 .supertool.json에 `