Install and what it turns on (한국어)
Sprag는 Claude Code와 Codex를 지원합니다. 기본 대상은 Claude Code이며, --agent codex를 붙이면 다른 연동은 그대로 두고 Codex 명령을 실행합니다.
Sprag는 Claude Code와 Codex를 지원합니다. 기본 대상은 Claude Code이며, --agent codex를 붙이면 다른 연동은 그대로 두고 Codex 명령을 실행합니다.
Codex 설치
npm i -g sprag-cli명령 하나로 두 에이전트를 함께 설정합니다. 설치는 Claude Code 연동과 동봉된 추천 룰을 전체 프로젝트에 등록하고, Codex가 설치되어 있으면(~/.codex 또는 $CODEX_HOME) Codex 훅과 AGENTS.md 하네스도 등록합니다. 설치 중에 묻는 것은 없으며, 단계마다 확인하려면 sprag install --manual을 쓰십시오.
남는 절차는 Codex 쪽 한 가지입니다. Codex에서 /hooks를 열어 Sprag 훅을 신뢰하십시오. Codex가 이 승인을 요구하므로 설치 프로그램이 대신할 수 없습니다. sprag doctor --agent codex는 문제가 생겼을 때만 쓰는 진단 명령입니다.
Claude Code 설정을 건드리지 않고 Codex만 쓰려면 다음과 같이 설치하십시오.
npm i -g sprag-cli --ignore-scripts
sprag install --agent codex별도 터미널에서는 sprag panel --agent codex, tmux에서는 sprag panel run --agent codex --를 사용합니다. 모델 위임은 직접 켜야 하며, 나중에 규칙을 추가할 때는 적용 범위를 지정해야 합니다. Codex 연동 안내에서 기능과 제한을 확인할 수 있습니다.
Claude Code 설치
사전 준비: Node.js ≥ 20 (node -v로 확인 · macOS brew install node · Windows winget install OpenJS.NodeJS.LTS · Linux/WSL은 nvm 권장)
npm i -g sprag-cli설치하면 Claude Code 화면 하단에 statusline이 곧바로 나타납니다. --ignore-scripts 옵션이나 sudo 사용 등으로 자동 등록이 되지 않았다면 sprag install을 실행해 직접 등록하십시오.
설치 한 번으로 statusline과 Skill, SessionStart 훅, 🅷 Harness(5원칙), 최초 route-scan이 모두 준비됩니다. Harness와 한국어 문체 지침은 무엇이 추가되는지 보여 준 뒤 켤지 물어봅니다. Harness는 ~/.claude/CLAUDE.md에 표시가 붙은 블록으로 추가되며, 기존에 작성해 둔 내용은 백업한 뒤 그대로 보존합니다. 이미 설정되어 있는 경우에는 아무것도 바꾸지 않습니다.
npm의 postinstall은 전역 npm 설치일 때만 설정을 실행합니다. 프로젝트 의존성으로 설치한 경우와 npx 캐시, CI가 설정된 환경에서는 건너뛰고 그 사실을 한 줄로 알립니다. 훅이 sprag 명령을 이름으로 호출하는데, 이런 설치는 sprag를 PATH에 올리지 않기 때문입니다. SPRAG_POSTINSTALL=1은 설정을 강제로 실행하고 SPRAG_POSTINSTALL=0은 건너뜁니다. 어느 경우든 sprag install을 직접 실행하면 같은 설정이 적용됩니다.
터미널이 아닌 환경(npm의 postinstall, CI, 파이프 입력)에서는 질문을 건너뛰고 기존 기본값을 적용합니다. 질문 없이 진행하려면 --yes나 --no-input, 아예 건너뛰려면 SPRAG_NO_HARNESS=1 npm i -g sprag-cli를 쓰십시오. 이미 적용한 설정을 되돌리려면 sprag harness uninit --global을 실행하십시오.
⚠️ sudo로 글로벌 설치를 하면 Skill이 사용자 계정이 아니라 root의
~/.claude에 등록되는 함정이 있습니다. nvm이나 fnm, Volta를 사용해 사용자 영역에 설치하기를 권장합니다.
설치하면 켜지는 기능과 직접 켜야 하는 기능
설치 시점에 비용이 들지 않는 기능은 전부 자동으로 켜집니다. 수동으로 남겨 둔 항목은 Claude Code 자체의 설정을 바꾸거나, 적용 범위를 사람이 정해 주어야 하는 것들뿐입니다.
| 기능 | 설치 직후 상태 | 끄는 방법 |
|---|---|---|
| statusline (진단 칩·절감 원장) | 켜짐 | sprag uninstall |
/claude-token-saver Skill | 켜짐 | 위와 같습니다 |
| SessionStart 훅 (route-scan 재분석) | 켜짐 | 위와 같습니다 |
| UserPromptSubmit 훅 (brief 주입) | 켜짐 | 위와 같습니다 |
| 최초 route-scan (최근 14일 로그 분석) | 설치 중 즉시 1회 실행 | 해당 없습니다 |
🅷 Harness 5원칙 (~/.claude/CLAUDE.md) | 켜짐 (터미널에서는 내용을 보여 주고 한 번 묻습니다) | harness uninit --global · SPRAG_NO_HARNESS=1 |
| doc2md 훅 (Read·Edit·Write·프롬프트) | 켜짐 | doc2md off · SPRAG_NO_DOC2MD=1 |
| doc2md 변환기(markitdown venv) | 터미널에서 설치 여부를 묻고, 비대화형 설치에서는 명령만 안내합니다 | doc2md install-converter 로 나중에 설치 |
| 한국어 문체 지침 | 시스템 로케일이 한국어면 켜짐 (터미널에서는 묻습니다) | korean off · SPRAG_NO_KOREAN=1 |
| compact-window 경고 칩 | 켜짐 | compact-window off |
| 업데이트 안내 칩 | 켜짐 | SPRAG_NO_UPDATE_CHECK=1 |
| ⭐ 스타 안내 (라우팅·doc2md 절감이 $10 에 이르면 하루 동안 한 번만) | 켜짐 | SPRAG_NO_NOTE=1 |
compact-window 값 고정 (autoCompactWindow 500k) | 꺼짐 — 직접 실행해야 합니다 | compact-window set --global 또는 --project |
모델 피팅 룰 승인 (ratchet-model.md 위임 룰) | 후보만 제안합니다 | route-scan rules 로 확인하고 승인·삭제 |
handoff (한도 임박 시 작업 백업) | 필요할 때 직접 실행하는 명령입니다 | 해당 없습니다 |
compact-window set 은 Claude Code 의 settings.json 에 값을 적고, 전역과 프로젝트 중 어디에 적을지는 사람이 정해야 하므로 자동으로 실행하지 않습니다. 모델 피팅 룰도 같은 이유로 승인 단계를 남겨 두었습니다. 어떤 작업을 더 싼 티어에 맡길지는 사용자의 판단이 필요합니다.
위 SPRAG_ 환경변수는 예전에 CTS_ 접두사를 썼습니다(CTS_NO_UPDATE_CHECK, CTS_NO_HARNESS 등). 예전 CTS_ 이름도 계속 읽으며, 둘 다 설정하면 SPRAG_ 쪽이 우선합니다.
네트워크 접근
Sprag 이 측정하는 값은 모두 사용자 컴퓨터의 파일에서 나옵니다. 아래 표는 Sprag 이 네트워크로 나가는 지점 전부이며, 게시된 패키지(3.68.0)를 정적으로 스캔해서 뽑은 목록에 3.70.0 의 옵트인 팀 레이어를 더한 것입니다. statusline 을 그리는 동안 네트워크를 기다리는 일은 없습니다. 요청은 분리된 자식 프로세스가 보내고, 그리는 쪽은 캐시된 답만 읽습니다.
| 목적지 | 시점 | 보내는 내용 | 끄는 방법 |
|---|---|---|---|
<npm 레지스트리>/sprag-cli/latest: 레지스트리는 npm_config_registry 나 ~/.npmrc 의 registry= 줄에서 가져오고(기본값 registry.npmjs.org), npmjs 로 대신 물어보지 않습니다 | statusline 에서 하루 한 번, SessionStart 훅에서 3시간마다 | 요청 자체만 보내고 식별 정보는 없습니다. 레지스트리 인증 토큰(_authToken)은 보내지 않으므로, 읽기에도 인증이 필요한 레지스트리에서는 확인이 실패합니다 | SPRAG_NO_UPDATE_CHECK=1 또는 NO_UPDATE_NOTIFIER=1 |
api.github.com/repos/rootstudioyaml/sprag/releases/tags/<버전> | 위 확인에서 새 버전이 보이면 그 릴리스의 핵심 세 줄을 가져옵니다 | 요청 자체만 보냅니다 | 위와 같습니다 |
https://hiycfjwswtkixyoqkznm.supabase.co/rest/v1/rpc/presets_version, presets_published (Supabase, 읽기 전용) | SessionStart 훅의 분리된 자식 프로세스가 최대 24시간에 한 번 확인합니다. presets_published 는 게시 버전이 바뀌었을 때만 부르고, sprag presets sync 로 바로 확인할 수도 있습니다 | 요청 자체만 보냅니다. 공개 anon 키를 쓰며 구성원 키나 식별 정보는 없습니다. 게시된 래칫·모델 라우팅·위임 에이전트 프리셋은 CLI 에 들어 있는 키로 서명이 확인될 때만 적용합니다. 오프라인이거나 막혀 있거나 서명이 맞지 않으면 패키지에 동봉된 프리셋을 계속 쓰고, sprag presets status 가 어느 쪽을 왜 쓰는지 알려 줍니다 | SPRAG_NO_PRESET_SYNC=1 또는 SPRAG_NO_UPDATE_CHECK=1 |
사용자의 LiteLLM 게이트웨이: GET /key/info, /user/info, /model/info, /spend/logs/v2, /global/spend/logs | ANTHROPIC_BASE_URL 이 게이트웨이를 가리키고 키가 있을 때만 동작합니다. /user/info, /spend/logs/v2, /global/spend/logs 는 팀 동기화도 부릅니다(팀에 참여한 동안 최대 5분에 한 번). 이 사용자의 하루 게이트웨이 지출을 읽기 위해서입니다. 하루 금액은 /spend/logs/v2 가 주는 요청 시각을 로컬 날짜로 묶어 계산합니다. 이 엔드포인트가 없는 게이트웨이에서는 UTC 날짜만 남기는 /global/spend/logs 로 대신합니다. 예산 게이지는 statusline 주기로, /model/info 는 sprag profile-map --refresh 를 실행할 때나 예산 갱신에 편승해서 갱신합니다. Codex 는 자체 설정의 provider 주소를 씁니다 | 사용자가 이미 쓰는 키를 Authorization 헤더에 넣습니다. 키는 Sprag 의 캐시 파일에 적지 않습니다 | ANTHROPIC_BASE_URL 을 해제하거나 sprag mode 에서 예산 세그먼트를 뺍니다 |
api.anthropic.com/api/oauth/usage | claude.ai 계정으로 로그인했고 요금제가 Pro 나 Max 가 아니며(Team, Enterprise 등) 게이트웨이, API 키, 클라우드 공급자를 쓰지 않을 때만 동작합니다. 분리된 자식 프로세스가 최대 5분에 한 번 갱신해 💳 budget 게이지를 그립니다 | Claude Code 가 이미 저장한 로그인 토큰을 Anthropic 에만 보냅니다. 토큰은 메모리에서만 쓰고 캐시 파일, 로그, 명령줄 인자에 적지 않습니다 | sprag mode no-oauth-budget 또는 SPRAG_OAUTH_BUDGET=0 |
gh CLI 를 통한 GitHub 이슈 | sprag feedback 을 실행했고 gh 가 로그인된 경우에만 | 입력한 메시지와 버전·OS·Node.js 버전 | --anonymous 를 붙이면 gh 경로를 건너뜁니다 |
docs.google.com/forms/…/formResponse | sprag feedback 을 실행했고 gh 를 쓸 수 없는 경우에만 | 같은 메시지와 메타데이터를 관리자가 읽는 익명 폼으로 보냅니다 | feedback 을 실행하지 않으면 됩니다. 실행하면 미리 채운 이슈 URL 과 함께 로컬 사본도 남습니다 |
npm install -g sprag-cli@<버전> | sprag upgrade 에서 제안을 수락한 뒤에만 | 일반 npm 설치입니다 | 제안을 거절합니다 |
npm install -g sprag-cli(또는 pnpm, bun, yarn 의 같은 명령) 다음 sprag install | 조직 운영자가 최소 Sprag 버전을 정해 둔 조직의 멤버이고 이 컴퓨터가 그보다 낮은 버전일 때만, 세션을 시작할 때 묻지 않고 분리된 백그라운드 프로세스로 실행합니다. 출력은 사용자 데이터 디렉터리의 org-upgrade.log 에 쌓이고, 결과는 다음 세션에서 알려 줍니다 | 일반 패키지 설치이며 식별자는 보내지 않습니다. 최소 버전 자체는 위 팀 룰 동기화로 받습니다 | sprag team leave 또는 SPRAG_NO_TEAM_SYNC=1(최소 버전을 더 이상 갱신하지 않습니다). git 체크아웃에서 실행한 사본은 스스로 업그레이드하지 않습니다 |
Sprag 전용 venv 에 pip install markitdown, Sprag 데이터 디렉터리에 npm install openfig-core | doc2md 변환기를 터미널에서 설치하기로 했을 때, 또는 문서가 처음 변환기를 필요로 할 때 | 일반 패키지 설치입니다. openfig-core 는 --ignore-scripts 로 설치합니다 | SPRAG_DOC2MD_NO_AUTOINSTALL=1 로 자동 설치만 막을 수 있습니다 |
https://hiycfjwswtkixyoqkznm.supabase.co/rest/v1/rpc/* (Supabase) | sprag team join 을 실행했거나 SPRAG_TEAM_TOKEN 이 설정된 경우에만, 이후 SessionStart 훅과 프롬프트 훅이 띄운 분리된 자식 프로세스가 5분마다 | 로컬 날짜별 하루 집계: 지출(USD), 절감(USD), 위임 실행 횟수, 모델 계열 비중, 모델 계열별 지출(USD), Claude·Codex·게이트웨이 지출(USD), 총지출(USD), 위임 비용(USD), Codex 위임 실행 횟수와 비용, 서브에이전트 비용(USD), 가격을 몰라 빠진 세션·실행의 수, 가명 처리한 게이트웨이 사용자 해시(게이트웨이 주소와 사용자 ID를 합쳐 해시한 값의 앞 16자리 16진수, 3.84.0부터 보냅니다), Sprag 버전, 에이전트, 표시 이름, 그리고 OS 이름과 버전(arch 인자는 항상 빈 값입니다. 호스트 이름, 사용자 이름, 경로는 제외. 참여 직후 한 번, 이후에는 바뀔 때만 member_set_info 로 보냅니다). 하루 집계와 별도로 위임 룰 요약 한 벌이 member_rules_report 로 올라갑니다(전체 동기화에서만, 내용이 바뀌었거나 하루가 지났을 때). 카테고리와 티어별로 상태(active 또는 review), 에피소드 수, 위임 횟수, 실패율, 기준선 실패율, 절감액(USD), 도구 호출과 출력 토큰 상한, 룰을 처음 등록한 날짜, 출처(수락한 Sprag 프리셋이면 preset, 내 route-scan이 학습한 룰이면 scan, 한 행에 둘이 섞였으면 both)만 담깁니다. 룰 본문, 예시, 프로젝트 경로는 들어가지 않습니다. 프롬프트, 트랜스크립트, 파일 경로, 프로젝트 이름, API 키는 보내지 않습니다. 룰 본문은 sprag team propose 를 실행할 때만, 새 표시 이름은 sprag team name 을 실행할 때만(member_set_name) 올라갑니다. 컴퓨터가 SPRAG_NO_TEAM_SYNC=1 이 켜진 것을 처음 봤을 때와 다시 꺼졌을 때, 상태만 담은 호출(member_set_sync, 사용량 데이터 없음)을 한 번씩 보냅니다. 팀 기능 참고 | sprag team leave 또는 SPRAG_NO_TEAM_SYNC=1(사용량 업로드를 모두 멈춤) |
https://hiycfjwswtkixyoqkznm.supabase.co/rest/v1/rpc/prompt_chunk_put (Supabase) | 팀 정책에서 프롬프트 수집이 켜진 엔터프라이즈 팀 구성원만 해당합니다. Claude Code 나 Codex 를 쓰는 동안 약 30분마다(프롬프트를 제출할 때 30분이 지났으면 분리된 백그라운드 업로드가 시작됩니다), 그리고 세션을 시작할 때 | 정책이 이 컴퓨터에 닿은 뒤 메인 Claude Code 와 Codex 세션에서 직접 입력한 프롬프트입니다. 시각, 프로젝트 폴더 이름, 본문(최대 20,000자)이 올라가고 눈에 띄는 비밀값은 [redacted] 로 바뀌고, 이메일 주소, 한국 전화번호, 주민등록번호, 카드번호도 업로드 전에 이 컴퓨터에서 [redacted:email], [redacted:phone], [redacted:rrn], [redacted:card] 로 바뀝니다. 어시스턴트 답변, 도구 출력, 파일 내용, 서브에이전트 기록, 파일 경로는 보내지 않습니다. 한 번에 최대 2,000건 또는 8MB입니다. 팀 레이어 참고 | 팀의 프롬프트 수집 정책(오너나 어드민), SPRAG_NO_TEAM_SYNC=1, sprag team leave |
팀에 참여하지 않는 한 사용량 데이터, 트랜스크립트 내용, 프로젝트 경로는 컴퓨터 밖으로 나가지 않습니다. 팀에 참여해도 팀이 받는 것은 위 표의 팀 레이어 줄에 적은 하루 집계, 위임 룰 요약과, 프롬프트 수집을 켠 엔터프라이즈 팀이라면 그다음 줄에 적은 프롬프트 업로드뿐입니다. 절감 원장과 히스토리 파일은 Skill 의 저장 위치 절에 적힌 사용자 데이터 디렉터리에만 남습니다. route-scan 룰도 본문, 예시, 프로젝트 경로는 그곳에 남고 카테고리별 숫자 요약만 올라갑니다.
Node 22.19 나 24.5 이상에서는 이 요청들이 Node 에 내장된 루트 인증서와 NODE_EXTRA_CA_CERTS 에 더해 운영체제의 인증서 저장소(macOS 키체인, Windows 인증서 저장소, Linux 시스템 번들)도 신뢰합니다. 그래서 회사 프록시가 시스템 저장소에만 설치된 루트 인증서로 HTTPS 를 다시 서명하는 환경에서도, 별도 설정 없이 업데이트 확인과 프리셋 동기화, 팀 동기화가 계속 동작합니다. 저장소는 첫 요청 직전에 한 번만 읽고, statusline 을 그리는 동안에는 읽지 않습니다. SPRAG_SYSTEM_CA=0 으로 끌 수 있습니다. NODE_USE_SYSTEM_CA=1 이나 --use-system-ca 를 쓰면 Node 가 이미 저장소를 읽어 두었으므로 Sprag 은 다시 읽지 않습니다. 그보다 오래된 Node 는 내장 루트 인증서만 쓰므로 NODE_EXTRA_CA_CERTS 를 설정하십시오.
다른 문서
- Codex 연동
- Statusline reference (한국어)
- Not a router (한국어)
- route-scan 동작 상세
- Harness, compact-window and seed (한국어)
- doc2md 상세 문서
- Gateways, pricing, FAQ and environment (한국어)
- Command reference (한국어)
- Sprag 이 보내는 데이터
- Korean writing guidance (한국어)
- 클로드 코드 토큰 사용량 줄이는 법
- 클로드 코드 5시간·주간 사용 한도 이해하기
- 코덱스 CLI 토큰 사용량 줄이는 법
- Sprag와 ccusage, claude-usage, 스테이터스라인 도구 비교