claude-pro-minmax 1.2.0 → 1.3.0

package/README.ko.md

@@ -15,13 +15,15 @@
 CPMM은 모델 라우팅, 출력 제어, 로컬 안전장치로 리셋 전까지 더 많은 검증된 작업을 완료하도록 돕습니다.
 
 > **설치 완료했다면 여기서 시작하세요: [사용자 가이드](docs/USER-MANUAL.ko.md)**
+>
+> **New in v1.3.0:** Bash-heavy 출력 축약을 위한 RTK 선택 통합.
 
 ---
 
 > [!TIP]
 > **🚀 3초 요약: 왜 이걸 써야 하나요?**
 > 1.  **배치 실행:** `/do`로 구현-검증을 한 흐름에서 처리하고, 필요할 때만 `/do-sonnet`/`/do-opus`로 승격합니다.
-> 2.  **출력 비용 제어:** 응답 예산과 CLI 필터링으로 불필요한 출력 토큰을 줄입니다.
+> 2.  **출력 비용 제어:** 응답 예산, CLI 필터링, 그리고 optional RTK로 Bash-heavy 출력량을 줄입니다.
 > 3.  **로컬 안전장치:** 로컬 Hook + 원자적 롤백으로 실패 시 빠르게 복구합니다.
 
 ---
@@ -50,13 +52,61 @@ cpmm setup
 cpmm doctor
 ```
 
+> **v1.3.0 참고:** `cpmm setup`은 지원 환경에서 RTK 설치를 시도합니다. RTK 활성화는 여전히 opt-in입니다.
+
 의존성 정책:
 - `required`: `jq`, `mgrep`, `tmux`
+- `optional` (자동 설치 시도): `rtk`
 - `optional` (확인만): `claude` (사전 설치 가정)
-- 자동 설치 지원: `npm` (mgrep), `brew` (macOS), Linux 패키지 매니저 `apt-get`, `dnf`, `pacman`, `apk`
+- 도구별 자동 설치 경로:
+  - `mgrep`: `npm`
+  - `rtk`: `brew` 또는 upstream `curl` installer
+  - `jq`, `tmux`: `brew` (macOS) 또는 Linux 패키지 매니저 `apt-get`, `dnf`, `pacman`, `apk`
 - macOS에서 Homebrew가 없으면 설치 명령을 안내합니다
 
-### 4. Perplexity/언어 설정 (선택)
+### 4. 커스텀 & 업데이트 정책
+
+- `cpmm setup`은 누락된 의존성을 설치한 뒤, CPMM 설정(설정 파일 복사, 언어 선택, Perplexity 설정)까지 진행합니다.
+- `cpmm doctor`는 수정 없이 의존성 상태와 RTK hook 상태를 확인합니다.
+- 재실행 시 CPMM 관리 파일은 최신 버전으로 교체되고, 사용자 데이터는 보존됩니다.
+
+```text
+~/.claude/*            ← Global Baseline (CPMM 관리)
+  ├── agents/            🔄 업데이트 시 교체됨
+  ├── commands/          🔄 업데이트 시 교체됨
+  ├── contexts/          🔄 업데이트 시 교체됨
+  ├── scripts/           🔄 업데이트 시 교체됨
+  ├── skills/cli-wrappers/ 🔄 업데이트 시 교체됨
+  ├── rules/*.md         🔄 업데이트 시 교체됨
+  ├── settings.json      🔄 업데이트 시 교체됨
+  ├── settings.local.json  ✋ 사용자 소유 — 보존됨
+  ├── skills/learned/      ✋ 사용자 소유 — 보존됨
+  ├── sessions/            ✋ 사용자 소유 — 보존됨
+  ├── plans/               ✋ 사용자 소유 — 보존됨
+  ├── projects/            ✋ 사용자 소유 — 보존됨
+  └── rules/language.md    ✋ 사용자 소유 — 보존됨
+
+<project>/.claude/*    ← Project-Specific (사용자/팀 커스텀)
+  ├── CLAUDE.md          프로젝트별 지침
+  ├── commands/          프로젝트 전용 슬래시 명령어
+  ├── skills/            프로젝트 전용 스킬
+  ├── rules/             프로젝트 전용 규칙
+  └── settings.json      프로젝트 전용 권한/훅/MCP 비활성화
+```
+
+> **핵심 규칙 2가지:**
+> 1. 글로벌 커스텀은 일반적으로 `settings.local.json`에 둡니다. `settings.json`은 CPMM 관리 대상이라 업데이트 시 덮어쓰기되므로, RTK 같은 third-party hook을 여기에 넣었다면 업데이트 후 다시 확인해야 합니다.
+> 2. 커스텀 명령어/규칙은 프로젝트 `.claude/`에 — 글로벌 `commands/`는 CPMM이 관리합니다.
+
+프로젝트 초기화 팁:
+- `claude` 실행 전에 `project-templates/`를 참고해 프로젝트를 초기화하세요. (설치기는 `project-templates`를 `~/.claude`로 복사하지 않습니다.)
+
+### 5. 고급 (선택)
+<details>
+<summary>Perplexity, 언어, 수동 설치 보기</summary>
+
+**Perplexity/언어 설정 (필수 아님):**
+- Perplexity는 `/dplan`의 웹 리서치에 사용됩니다. 설정하지 않아도 `/dplan`은 Sequential Thinking + Context7으로 동작하며, 나머지 모든 기능은 Perplexity와 무관합니다.
 - 최초 인터랙티브 설치 시 `cpmm setup`이 출력 언어와 Perplexity API 키를 묻습니다.
 - 영어(기본): 파일이 필요 없습니다. `~/.claude/rules/language.md`가 있으면 삭제하세요.
 - 비영어: `~/.claude/rules/language.md`를 만들어 원하는 언어를 지정하세요.
@@ -72,11 +122,7 @@ cpmm doctor
 }
 ```
 
-### 5. 고급 (선택)
-<details>
-<summary>수동 의존성 설치와 소스 설치 보기</summary>
-
-수동 의존성 설치:
+**수동 의존성 설치:**
 ```bash
 # jq
 brew install jq                 # macOS
@@ -97,7 +143,7 @@ sudo pacman -S --noconfirm tmux # Arch
 sudo apk add tmux               # Alpine
 ```
 
-소스에서 수동 설치:
+**소스에서 수동 설치:**
 ```bash
 git clone https://github.com/move-hoon/claude-pro-minmax.git
 cd claude-pro-minmax
@@ -106,20 +152,53 @@ node bin/cpmm.js setup
 # bash install.sh
 ```
 
-설치 동작:
-- `cpmm setup`은 누락된 의존성을 설치한 뒤, CPMM 설정(설정 파일 복사, 언어 선택, Perplexity 설정)까지 진행합니다.
-- `cpmm doctor`는 수정 없이 의존성 상태만 확인합니다.
-- 재실행 시 CPMM 관리 파일만 갱신하고, `language.md`, `settings.local.json`, `skills/learned/`, `sessions/` 등 사용자 파일은 보존합니다.
+</details>
 
-프로젝트 초기화 팁:
-- `claude` 실행 전에 `project-templates/`를 참고해 프로젝트를 초기화하세요. (설치기는 `project-templates`를 `~/.claude`로 복사하지 않습니다.)
+### 6. Bash 출력 최적화 (RTK)
 
-</details>
+RTK는 CPMM이 지원하는 **선택적 출력 최적화 계층**입니다. `cpmm setup`은 RTK 바이너리 설치를 시도하지만, RTK hook은 기본 활성화하지 않습니다.
+
+권장 opt-in 절차:
+
+```bash
+rtk init -g --hook-only
+cpmm doctor
+```
+
+권장 `PreToolUse` 순서 (`~/.claude/settings.json`):
+- 먼저 CPMM safety hook: `~/.claude/scripts/hooks/critical-action-check.sh` with `timeout: 5`
+- 그 다음 RTK rewrite hook: `~/.claude/hooks/rtk-rewrite.sh` with `timeout: 10`
+
+업데이트 참고:
+- `cpmm setup`은 업데이트 시 `~/.claude/settings.json`을 다시 씁니다.
+- RTK를 opt-in으로 사용 중이면 CPMM 업데이트 후 hook 순서와 timeout을 다시 확인하고, `cpmm doctor`를 다시 실행하세요.
+
+권장 검증:
+- `/hooks`에서 CPMM hook과 RTK hook이 모두 로드되는지 확인
+- 위험 명령이 여전히 CPMM에서 먼저 차단되는지 확인
+- `cpmm doctor` 실행
+- 실제 Bash-heavy 세션 후 `rtk gain --quota --tier pro` 확인
+
+롤백:
+
+```bash
+rtk init -g --uninstall
+```
 
 ---
 
 ## 🚀 빠른 시작 (Quick Start)
 
+### ⚡ 첫 60초 (FTUE)
+
+```bash
+claude
+> /plan 이 저장소를 분석하고 작은 개선 1개에 대한 3단계 실행 계획을 제안해줘.
+> /do 1단계만 최소 변경으로 안전하게 구현해줘.
+> /review .
+> /session-save ftue-first-pass
+```
+
 ### 🤖 에이전트 워크플로우
 
 CPMM은 계층적 모델 라우팅을 제공합니다: `/plan`은 @planner (Sonnet 4.6) → @builder (Haiku 4.5) 체인으로 복잡한 작업을 처리하고, `/do`는 현재 세션 모델에서 직접 실행하여 속도를 높입니다.
@@ -413,7 +492,7 @@ A: 네, 하지만 이러한 최적화가 필요하지 않을 수 있습니다. M
 <details>
 <summary><strong>Q: 기존 Claude Code 설정과 충돌하나요?</strong></summary>
 
-A: 최초 `cpmm setup` 시 기존 `~/.claude`를 `~/.claude.pre-cpmm`으로 백업합니다. 재실행 시 CPMM 관리 파일만 갱신하고, 언어 설정·로컬 설정·학습된 패턴·세션 기록은 보존됩니다.
+A: 최초 `cpmm setup` 시 기존 `~/.claude`를 `~/.claude.pre-cpmm`으로 백업합니다. 재실행 시 CPMM 관리 경로는 재생성되고, 사용자 소유 경로(언어 설정, 로컬 설정, 학습 패턴, 세션)는 보존됩니다. 정확한 경계는 설치 섹션의 2-Layer 구조를 참고하세요.
 </details>
 
 <details>
@@ -431,7 +510,22 @@ A: API 가격(컴퓨팅 비용 반영)을 보면 Opus 4.6 ($5/MTok input)은 Son
 <details>
 <summary><strong>Q: /do 실행 중 실패하면 어떻게 되나요?</strong></summary>
 
-A: CPMM은 **원자적 롤백**을 사용합니다. `/do` 실행 전 `git stash push`로 스냅샷을 저장합니다. 2회 재시도 후 실패하면 `git stash pop`이 작업 트리를 실행 전 상태로 복원합니다. dirty state를 방지하고 수동 정리에 소비될 2-4 메시지를 절약합니다.
+A: CPMM은 `scripts/snapshot.sh`를 통한 **best-effort 원자적 롤백**을 사용합니다.
+
+- `/do` 실행 전 `snapshot.sh push`로 라벨된 stash 스냅샷을 시도합니다.
+- 실패 시 `snapshot.sh pop`이 복구를 시도하며, 아래 상태 중 하나를 반환합니다:
+
+| 상태 | 의미 |
+| --- | --- |
+| `RESTORED` | CPMM 라벨 stash를 정상 pop하여 복구 완료 |
+| `RESTORE_FAILED` | `git stash pop` 실패 (예: 충돌) |
+| `CHECKOUT_CLEAN` | CPMM stash가 없어 fallback `git checkout .` 성공 |
+| `CLEAN_FAILED` | fallback 정리도 실패 |
+
+롤백 후에도 완전히 깨끗하지 않다면:
+1. `git status` 확인
+2. `git stash list` 확인
+3. 충돌 해결/새 untracked 파일 수동 정리 후 재시도
 
 - 비용: 0 (git stash는 로컬 작업)
 - 제한: 기존(tracked) 파일만 추적. 새로 생성된 파일은 수동 제거 필요.
@@ -442,6 +536,7 @@ A: CPMM은 **원자적 롤백**을 사용합니다. `/do` 실행 전 `git stash
 ## 참고 링크
 
 - 핵심전략 근거 실험 아카이브: [핵심전략 실험 아카이브](docs/CORE_STRATEGY_EXPERIMENT_ARCHIVE.ko.md)
+- 방향성 비교를 위한 외부 역분석 사례: [claude-limits](https://she-llac.com/claude-limits) (Claude 플랜 usage/credits 동작을 설명하려는 비공식 분석)
 - 공식 문서:
   - [Anthropic Pricing](https://docs.anthropic.com/en/docs/about-claude/pricing)
   - [Usage Limit Best Practices](https://support.claude.com/en/articles/9797557-usage-limit-best-practices)

package/README.md

@@ -15,13 +15,15 @@
 CPMM helps Pro users complete more verified tasks before reset through model routing, output control, and local safety rails.
 
 > **Already installed? Start here: [User Guide](docs/USER-MANUAL.md)**
+>
+> **New in v1.3.0:** Optional RTK integration for Bash-heavy output reduction.
 
 ---
 
 > [!TIP]
 > **🚀 3-Second Summary: Why use this?**
 > 1.  **Batch Execution:** Use `/do` to keep implementation and verification in one flow, and escalate to `/do-sonnet`/`/do-opus` only when needed.
-> 2.  **Output Cost Control:** Use response budgets and CLI filtering to reduce unnecessary output tokens.
+> 2.  **Output Cost Control:** Use response budgets, CLI filtering, and optional RTK for Bash-heavy output reduction.
 > 3.  **Local Safety Rails:** Local hooks and atomic rollback help you recover quickly on failure.
 
 ---
@@ -50,13 +52,61 @@ cpmm setup
 cpmm doctor
 ```
 
+> **v1.3.0 note:** `cpmm setup` now attempts RTK installation when supported. RTK activation remains opt-in.
+
 Dependency policy:
 - `required`: `jq`, `mgrep`, `tmux`
+- `optional` (auto-install attempt): `rtk`
 - `optional` (check only): `claude` (assumed pre-installed)
-- auto-install supports `npm` (mgrep), `brew` (macOS), and Linux package managers `apt-get`, `dnf`, `pacman`, `apk`
+- auto-install paths by tool:
+  - `mgrep`: `npm`
+  - `rtk`: `brew` or upstream `curl` installer
+  - `jq`, `tmux`: `brew` (macOS) or Linux package managers `apt-get`, `dnf`, `pacman`, `apk`
 - on macOS without Homebrew, setup prints the Homebrew install command
 
-### 4. Perplexity and Language (Optional)
+### 4. Customization & Update Policy
+
+- `cpmm setup` installs missing dependencies, then configures CPMM (copies config files, language selection, Perplexity setup).
+- `cpmm doctor` checks dependency status and RTK hook health without modifying anything.
+- Re-running `cpmm setup` replaces CPMM-managed files with the latest version while preserving user data.
+
+```text
+~/.claude/*            ← Global Baseline (CPMM-managed)
+  ├── agents/            🔄 Replaced on update
+  ├── commands/          🔄 Replaced on update
+  ├── contexts/          🔄 Replaced on update
+  ├── scripts/           🔄 Replaced on update
+  ├── skills/cli-wrappers/ 🔄 Replaced on update
+  ├── rules/*.md         🔄 Replaced on update
+  ├── settings.json      🔄 Replaced on update
+  ├── settings.local.json  ✋ User-owned — preserved
+  ├── skills/learned/      ✋ User-owned — preserved
+  ├── sessions/            ✋ User-owned — preserved
+  ├── plans/               ✋ User-owned — preserved
+  ├── projects/            ✋ User-owned — preserved
+  └── rules/language.md    ✋ User-owned — preserved
+
+<project>/.claude/*    ← Project-Specific (user/team customization)
+  ├── CLAUDE.md          Project-specific instructions
+  ├── commands/          Project-specific slash commands
+  ├── skills/            Project-specific skills
+  ├── rules/             Project-specific rules
+  └── settings.json      Project-specific permissions/hooks/MCP disable
+```
+
+> **Two key rules:**
+> 1. Global customization generally goes in `settings.local.json`. `settings.json` is CPMM-managed and overwritten on update; if you opt into RTK or other third-party hooks there, re-check them after updates.
+> 2. Custom commands/rules go in project `.claude/` — global `commands/` is managed by CPMM.
+
+Project initialization tip:
+- Before running `claude`, initialize your project with templates in `project-templates/` (not copied into `~/.claude`).
+
+### 5. Advanced (Optional)
+<details>
+<summary>Perplexity, language, manual install</summary>
+
+**Perplexity/Language setup (not required):**
+- Perplexity is used for web research in `/dplan`. Without it, `/dplan` still works via Sequential Thinking + Context7. All other features are unrelated to Perplexity.
 - On fresh interactive installs, `cpmm setup` asks for output language and Perplexity API key.
 - English (default): no file needed; remove `~/.claude/rules/language.md` if it exists.
 - Non-English: create `~/.claude/rules/language.md` with your preferred language.
@@ -72,11 +122,7 @@ Dependency policy:
 }
 ```
 
-### 5. Advanced (Optional)
-<details>
-<summary>Show manual dependency setup and source install</summary>
-
-Manual dependency setup:
+**Manual dependency setup:**
 ```bash
 # jq
 brew install jq                 # macOS
@@ -97,7 +143,7 @@ sudo pacman -S --noconfirm tmux # Arch
 sudo apk add tmux               # Alpine
 ```
 
-Manual install from source:
+**Manual install from source:**
 ```bash
 git clone https://github.com/move-hoon/claude-pro-minmax.git
 cd claude-pro-minmax
@@ -106,20 +152,53 @@ node bin/cpmm.js setup
 # bash install.sh
 ```
 
-Install behavior:
-- `cpmm setup` installs missing dependencies, then configures CPMM (copies config files, language selection, Perplexity setup).
-- `cpmm doctor` checks dependency status without modifying anything.
-- Re-running `cpmm setup` updates CPMM-managed files in place and preserves user-owned files like `language.md`, `settings.local.json`, `skills/learned/`, and `sessions/`.
+</details>
 
-Project initialization tip:
-- Before running `claude`, initialize your project with templates in `project-templates/` (not copied into `~/.claude`).
+### 6. Bash Output Optimization (RTK)
 
-</details>
+CPMM supports RTK as an **optional output-optimization layer** for Bash-heavy workflows. `cpmm setup` attempts to install the RTK binary, but CPMM does **not** enable the RTK hook by default.
+
+Recommended opt-in flow:
+
+```bash
+rtk init -g --hook-only
+cpmm doctor
+```
+
+Recommended `PreToolUse` order in `~/.claude/settings.json`:
+- CPMM safety hook first: `~/.claude/scripts/hooks/critical-action-check.sh` with `timeout: 5`
+- RTK rewrite hook second: `~/.claude/hooks/rtk-rewrite.sh` with `timeout: 10`
+
+Update note:
+- `cpmm setup` rewrites `~/.claude/settings.json` on update.
+- If you opt into RTK, re-check hook order and timeout after each CPMM update, then run `cpmm doctor`.
+
+Recommended verification:
+- Run `/hooks` and confirm both CPMM and RTK hooks are loaded
+- Confirm dangerous commands are still blocked by CPMM
+- Run `cpmm doctor`
+- After real Bash-heavy sessions, inspect `rtk gain --quota --tier pro`
+
+Rollback:
+
+```bash
+rtk init -g --uninstall
+```
 
 ---
 
 ## 🚀 Quick Start
 
+### ⚡ First 60 Seconds (FTUE)
+
+```bash
+claude
+> /plan Analyze this repository and propose a 3-step implementation plan for one small improvement.
+> /do Implement step 1 only, with minimal and safe changes.
+> /review .
+> /session-save ftue-first-pass
+```
+
 ### 🤖 Agent Workflow
 
 CPMM provides layered model routing: `/plan` chains @planner (Sonnet 4.6) → @builder (Haiku 4.5) for complex tasks, while `/do` executes directly in the current session model for speed.
@@ -413,7 +492,7 @@ This configuration is specifically designed for the Pro Plan's 5-hour rolling re
 <details>
 <summary><strong>Q: Does it conflict with existing Claude Code settings?</strong></summary>
 
-A: On first `cpmm setup`, CPMM backs up your existing `~/.claude` to `~/.claude.pre-cpmm`. Re-running `cpmm setup` updates CPMM-managed files in place — your language settings, local config, learned patterns, and session history are preserved.
+A: On first `cpmm setup`, CPMM backs up your existing `~/.claude` to `~/.claude.pre-cpmm`. Re-running `cpmm setup` recreates CPMM-managed paths and preserves user-owned paths (language settings, local config, learned patterns, sessions). See the 2-Layer structure in the install section for exact boundaries.
 </details>
 
 <details>
@@ -431,7 +510,22 @@ A: API pricing (reflecting compute cost), Opus 4.6 ($5/MTok input) is much more
 <details>
 <summary><strong>Q: What happens when /do fails mid-execution?</strong></summary>
 
-A: CPMM uses **Atomic Rollback**. Before `/do` executes, `git stash push` saves a snapshot. If execution fails after 2 retries, `git stash pop` restores the working tree to its pre-execution state. This prevents dirty state and saves 2-4 messages that would otherwise be spent on manual cleanup.
+A: CPMM uses **best-effort atomic rollback** via `scripts/snapshot.sh`.
+
+- Before `/do`, `snapshot.sh push` attempts a labeled stash snapshot.
+- On failure, `snapshot.sh pop` attempts restore and returns one of these statuses:
+
+| Status | Meaning |
+| --- | --- |
+| `RESTORED` | Labeled CPMM stash was popped successfully. |
+| `RESTORE_FAILED` | `git stash pop` failed (for example: conflicts). |
+| `CHECKOUT_CLEAN` | No CPMM stash found; fallback `git checkout .` succeeded. |
+| `CLEAN_FAILED` | Fallback cleanup also failed. |
+
+If rollback did not fully restore clean state:
+1. Run `git status`.
+2. Run `git stash list`.
+3. Resolve conflicts / remove new untracked files manually, then retry.
 
 - Cost: Zero (git stash is a local operation)
 - Limitation: Only tracks existing (tracked) files. Newly created files require manual removal.
@@ -442,6 +536,7 @@ A: CPMM uses **Atomic Rollback**. Before `/do` executes, `git stash push` saves
 ## References
 
 - Archived experiment evidence for core strategy: [Core Strategy Experiment Archive](docs/CORE_STRATEGY_EXPERIMENT_ARCHIVE.md)
+- Independent reverse-engineering case study for direction-checking: [claude-limits](https://she-llac.com/claude-limits) (unofficial analysis of Claude plan usage/credits behavior)
 - Official pricing and usage docs:
   - [Anthropic Pricing](https://docs.anthropic.com/en/docs/about-claude/pricing)
   - [Usage Limit Best Practices](https://support.claude.com/en/articles/9797557-usage-limit-best-practices)

package/install.sh

@@ -47,6 +47,11 @@ else
 fi
 
 # Backup existing ~/.claude (Fresh Install Only)
+HAS_EXISTING_RTK_HOOK=false
+if [ -f "$HOME/.claude/settings.json" ] && grep -q "rtk-rewrite.sh" "$HOME/.claude/settings.json" 2>/dev/null; then
+  HAS_EXISTING_RTK_HOOK=true
+fi
+
 if [ "$IS_UPDATE" = false ] && [ -d "$HOME/.claude" ]; then
   if [ -d "$HOME/.claude.pre-cpmm" ]; then
     echo "⚠️  ~/.claude.pre-cpmm already exists, skipping backup."
@@ -283,9 +288,26 @@ echo "  > /dplan Analyze complex architecture"
 echo "  > /do Implement the login page"
 echo ""
 echo "Dependency Check:"
-echo "  cpmm setup       # install missing deps (jq, mgrep, tmux)"
+echo "  cpmm setup       # install missing deps (jq, mgrep, tmux) + attempt optional RTK install"
 echo "  cpmm doctor      # check status only"
 echo ""
+if command -v rtk >/dev/null 2>&1; then
+  echo "RTK (Optional Integration):"
+  echo "  Installed: rtk"
+  echo "  Enable hook: rtk init -g --hook-only"
+  echo "  Recommended Bash hook order in ~/.claude/settings.json:"
+  echo "    1) ~/.claude/scripts/hooks/critical-action-check.sh  (timeout: 5)"
+  echo "    2) ~/.claude/hooks/rtk-rewrite.sh                    (timeout: 10)"
+  echo "  Rollback: rtk init -g --uninstall"
+  echo ""
+fi
+if [ "$HAS_EXISTING_RTK_HOOK" = true ]; then
+  echo "RTK Update Note:"
+  echo "  An RTK hook was detected before this CPMM update."
+  echo "  Because CPMM reinstalled ~/.claude/settings.json, re-check RTK hook order and timeout."
+  echo "  Run: cpmm doctor"
+  echo ""
+fi
 echo "Language:"
 echo "  To change language: edit ~/.claude/rules/language.md"
 echo "  To use English: rm ~/.claude/rules/language.md"

package/lib/cli.js

@@ -4,14 +4,22 @@ const { execSync, spawnSync } = require("node:child_process");
 const path = require("node:path");
 const fs = require("node:fs");
 const pkg = require("../package.json");
+const {
+  RTK_DOCS_URL,
+  attemptRtkInstall,
+  getRtkManualInstallHints,
+  inspectRtkStatus,
+} = require("./rtk");
 
 const DEPS = [
   {
     key: "claude",
     command: "claude",
     required: false,
+    prerequisite: true,
     installKind: "skip",
-    description: "Claude Code CLI (assumed pre-installed)",
+    description: "Claude Code CLI",
+    installHint: "curl -fsSL https://claude.ai/install.sh | bash",
   },
   {
     key: "jq",
@@ -40,6 +48,11 @@ const DEPS = [
   },
 ];
 
+function colorize(text, colorCode) {
+  if (!process.stdout.isTTY || process.env.NO_COLOR) return text;
+  return `\x1b[${colorCode}m${text}\x1b[0m`;
+}
+
 function commandExists(cmd) {
   try {
     execSync(`command -v ${cmd}`, { stdio: "ignore" });
@@ -119,15 +132,120 @@ function checkDeps() {
 }
 
 function printStatus(results) {
-  console.log("");
-  for (const r of results) {
-    const icon = r.installed ? "OK" : (r.required ? "MISSING" : "SKIP");
+  const prereqs = results.filter((r) => r.prerequisite);
+  const deps = results.filter((r) => !r.prerequisite);
+
+  if (prereqs.length > 0) {
+    console.log("\nPrerequisite:");
+    for (const r of prereqs) {
+      if (r.installed) {
+        console.log(`  ${colorize("✓", "32")} ${r.key.padEnd(8)} ${r.description}`);
+      } else {
+        console.log(`  ${colorize("⚠", "33")} ${r.key.padEnd(8)} ${r.description} — ${colorize("not found", "33")}`);
+        if (r.installHint) {
+          console.log(`             Install: ${r.installHint}`);
+        }
+      }
+    }
+  }
+
+  console.log("\nDependencies:");
+  for (const r of deps) {
+    const icon = r.installed
+      ? colorize("✓", "32")
+      : (r.required ? colorize("✗", "31") : colorize("○", "33"));
     const tag = r.required ? "[required]" : "[optional]";
     console.log(`  ${icon} ${r.key.padEnd(8)} ${tag} ${r.description}`);
   }
   console.log("");
 }
 
+function printRtkSetupResult(result) {
+  if (!result) return;
+
+  console.log("RTK Integration:");
+  switch (result.outcome) {
+    case "already_installed":
+      console.log(`  ${colorize("✓", "32")} rtk      [optional] already installed`);
+      break;
+    case "installed":
+      console.log(`  ${colorize("✓", "32")} rtk      [optional] installed (${result.method})`);
+      break;
+    default:
+      console.log(`  ${colorize("⚠", "33")} rtk      [optional] ${result.message}`);
+      for (const line of getRtkManualInstallHints()) {
+        console.log(`             ${line}`);
+      }
+      break;
+  }
+
+  console.log("  Optional activation:");
+  console.log("             1) rtk init -g --hook-only");
+  console.log("             2) Add ~/.claude/hooks/rtk-rewrite.sh after CPMM critical-action-check.sh");
+  console.log("             3) Set RTK hook timeout to 10");
+  console.log("             4) Re-run: cpmm doctor");
+  console.log("");
+}
+
+function printRtkDoctorStatus(status) {
+  console.log("\nRTK Integration:");
+  console.log(
+    `  ${status.binaryInstalled ? colorize("✓", "32") : colorize("○", "33")} rtk binary        ${
+      status.binaryInstalled ? "installed" : "not installed (optional)"
+    }`,
+  );
+
+  if (status.failReason === "missing_settings_json") {
+    console.log(`  ${colorize("✗", "31")} settings.json      missing (~/.claude/settings.json)`);
+    console.log("             Fix: re-run cpmm setup");
+    console.log("");
+    return { failed: true };
+  }
+
+  if (status.failReason === "invalid_settings_json") {
+    console.log(`  ${colorize("✗", "31")} settings.json      invalid JSON`);
+    console.log("             Fix: repair ~/.claude/settings.json, then re-run cpmm doctor");
+    console.log("");
+    return { failed: true };
+  }
+
+  if (!status.cpmmHookFound) {
+    console.log(`  ${colorize("✗", "31")} CPMM hook          critical-action-check.sh missing`);
+    console.log("             Fix: re-run cpmm setup");
+    console.log("");
+    return { failed: true };
+  }
+
+  console.log(`  ${colorize("✓", "32")} CPMM hook          critical-action-check.sh detected`);
+
+  if (!status.hookEnabled) {
+    console.log(`  ${colorize("○", "33")} RTK hook           not enabled (opt-in)`);
+    console.log(`             Enable: rtk init -g --hook-only`);
+    console.log(`             Docs: ${RTK_DOCS_URL}`);
+    console.log("");
+    return { failed: false };
+  }
+
+  if (status.orderOk) {
+    console.log(`  ${colorize("✓", "32")} Hook order         CPMM safety hook precedes RTK hook`);
+  } else {
+    console.log(`  ${colorize("✗", "31")} Hook order         RTK hook precedes CPMM safety hook`);
+    console.log("             Fix order in ~/.claude/settings.json:");
+    console.log("             1) ~/.claude/scripts/hooks/critical-action-check.sh (timeout: 5)");
+    console.log("             2) ~/.claude/hooks/rtk-rewrite.sh (timeout: 10)");
+  }
+
+  if (status.timeoutOk) {
+    console.log(`  ${colorize("✓", "32")} RTK timeout        10`);
+  } else {
+    const rendered = status.timeoutValue == null ? "missing" : String(status.timeoutValue);
+    console.log(`  ${colorize("⚠", "33")} RTK timeout        ${rendered} (recommended: 10)`);
+  }
+
+  console.log("");
+  return { failed: !status.orderOk };
+}
+
 function runSetup() {
   console.log(`CPMM v${pkg.version} - Setup`);
 
@@ -159,6 +277,9 @@ function runSetup() {
     printStatus(results);
   }
 
+  const rtkResult = attemptRtkInstall();
+  printRtkSetupResult(rtkResult);
+
   // Run install.sh for config files, language, and Perplexity setup
   if (!runInstallScript()) {
     return 1;
@@ -191,13 +312,16 @@ function runDoctor() {
   const results = checkDeps();
   printStatus(results);
 
+  const rtkStatus = inspectRtkStatus(path.join(process.env.HOME || process.env.USERPROFILE || "", ".claude", "settings.json"));
+  const rtkDoctor = printRtkDoctorStatus(rtkStatus);
+
   const missing = results.filter((r) => r.required && !r.installed);
-  if (missing.length > 0) {
+  if (missing.length > 0 || rtkDoctor.failed) {
     console.log(`Fix: cpmm setup`);
     return 1;
   }
 
-  console.log("All checks passed.");
+  console.log(colorize("All required checks passed.", "32"));
   return 0;
 }
 
@@ -205,8 +329,8 @@ function printHelp() {
   console.log(`CPMM v${pkg.version}
 
 Usage:
-  cpmm setup      Install deps + configure CPMM (language, Perplexity)
-  cpmm doctor     Check dependency status
+  cpmm setup      Install deps + configure CPMM (language, Perplexity, optional RTK)
+  cpmm doctor     Check dependency and RTK hook status
   cpmm --help     Show this help
   cpmm --version  Show version
 `);

package/lib/rtk.js

@@ -0,0 +1,179 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { execSync, spawnSync } = require("node:child_process");
+
+const RTK_INSTALL_URL = "https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh";
+const RTK_DOCS_URL = "https://github.com/rtk-ai/rtk/blob/main/docs/INSTALL.md";
+const CPMM_HOOK_NAME = "critical-action-check.sh";
+const RTK_HOOK_NAME = "rtk-rewrite.sh";
+
+function commandExists(cmd) {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runCommand(bin, args, label) {
+  const rendered = [bin, ...args].join(" ");
+  console.log(`  $ ${rendered}`);
+  const result = spawnSync(bin, args, { stdio: "inherit", env: { ...process.env } });
+  if (result.status !== 0) {
+    console.error(`  FAIL: ${label} (exit ${result.status})`);
+    return false;
+  }
+  return true;
+}
+
+function getRtkManualInstallHints() {
+  return [
+    "RTK is optional. CPMM setup will continue without it.",
+    "Install RTK manually with one of these upstream-supported methods:",
+    "  - brew install rtk",
+    `  - curl -fsSL ${RTK_INSTALL_URL} | sh`,
+    `  - Docs: ${RTK_DOCS_URL}`,
+  ];
+}
+
+function attemptRtkInstall() {
+  if (commandExists("rtk")) {
+    return {
+      ok: true,
+      outcome: "already_installed",
+      method: "existing",
+      message: "RTK already installed.",
+    };
+  }
+
+  if (commandExists("brew")) {
+    const ok = runCommand("brew", ["install", "rtk"], "rtk (brew)");
+    if (ok) {
+      return {
+        ok: true,
+        outcome: "installed",
+        method: "brew",
+        message: "RTK installed via Homebrew.",
+      };
+    }
+  }
+
+  if (commandExists("curl")) {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "cpmm-rtk-"));
+    const scriptPath = path.join(tempDir, "install.sh");
+    try {
+      const downloaded = runCommand("curl", ["-fsSL", RTK_INSTALL_URL, "-o", scriptPath], "rtk installer download");
+      const installed = downloaded ? runCommand("sh", [scriptPath], "rtk installer") : false;
+      return {
+        ok: installed,
+        outcome: installed ? "installed" : "manual_action_required",
+        method: "curl",
+        message: installed ? "RTK installed via upstream installer." : "RTK upstream installer failed.",
+      };
+    } finally {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+
+  return {
+    ok: false,
+    outcome: "manual_action_required",
+    method: "manual",
+    message: "No supported automatic RTK installer found.",
+  };
+}
+
+function matcherIncludesBash(matcher) {
+  return String(matcher || "")
+    .split("|")
+    .map((token) => token.trim())
+    .includes("Bash");
+}
+
+function flattenBashHooks(settings) {
+  const entries = Array.isArray(settings?.hooks?.PreToolUse) ? settings.hooks.PreToolUse : [];
+  const flattened = [];
+
+  entries.forEach((entry, entryIndex) => {
+    if (!matcherIncludesBash(entry?.matcher)) return;
+    const hooks = Array.isArray(entry?.hooks) ? entry.hooks : [];
+    hooks.forEach((hook, hookIndex) => {
+      flattened.push({
+        entryIndex,
+        hookIndex,
+        command: String(hook?.command || ""),
+        timeout: hook?.timeout,
+      });
+    });
+  });
+
+  return flattened;
+}
+
+function inspectRtkStatus(settingsPath) {
+  const result = {
+    binaryInstalled: commandExists("rtk"),
+    settingsPath,
+    cpmmHookFound: false,
+    hookEnabled: false,
+    orderOk: null,
+    timeoutValue: null,
+    timeoutOk: null,
+    failReason: null,
+    warnings: [],
+  };
+
+  if (!fs.existsSync(settingsPath)) {
+    result.failReason = "missing_settings_json";
+    return result;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+  } catch {
+    result.failReason = "invalid_settings_json";
+    return result;
+  }
+
+  const hooks = flattenBashHooks(parsed);
+  const cpmmIndex = hooks.findIndex((hook) => hook.command.includes(CPMM_HOOK_NAME));
+  if (cpmmIndex === -1) {
+    result.failReason = "missing_cpmm_hook";
+    return result;
+  }
+
+  result.cpmmHookFound = true;
+
+  const rtkIndex = hooks.findIndex((hook) => hook.command.includes(RTK_HOOK_NAME));
+  if (rtkIndex === -1) {
+    return result;
+  }
+
+  result.hookEnabled = true;
+  result.orderOk = cpmmIndex < rtkIndex;
+  if (!result.orderOk) {
+    result.failReason = "rtk_precedes_cpmm";
+  }
+
+  const rtkHook = hooks[rtkIndex];
+  result.timeoutValue = typeof rtkHook.timeout === "number" ? rtkHook.timeout : null;
+  result.timeoutOk = result.timeoutValue === 10;
+  if (!result.timeoutOk) {
+    result.warnings.push("rtk_timeout_not_10");
+  }
+
+  return result;
+}
+
+module.exports = {
+  RTK_DOCS_URL,
+  RTK_INSTALL_URL,
+  attemptRtkInstall,
+  getRtkManualInstallHints,
+  inspectRtkStatus,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-pro-minmax",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Quota-first routing and safety layer for Claude Code Pro workflows.",
   "author": "donghoon <move-hoon@users.noreply.github.com>",
   "license": "MIT",

package/scripts/hooks/README.ko.md

@@ -77,6 +77,16 @@ flowchart TB
 
 **비용 설명:** 모든 Hook은 머신에서 로컬로 실행되어 API 호출이 없습니다. Hook이 Claude에게 메시지를 표시할 때만(예: 명령 차단, 컴팩션 제안) 해당 메시지가 입력 토큰을 소비하며, 이러한 메시지는 의도적으로 간결합니다.
 
+## RTK 순서
+
+RTK를 opt-in으로 사용할 때는 CPMM의 Bash safety hook를 먼저 두고, RTK rewrite hook를 그 뒤에 둡니다.
+
+권장 순서 (`~/.claude/settings.json`):
+- `~/.claude/scripts/hooks/critical-action-check.sh` with `timeout: 5`
+- `~/.claude/hooks/rtk-rewrite.sh` with `timeout: 10`
+
+이 순서를 유지해야 CPMM의 위험 명령 차단이 RTK rewrite보다 먼저 실행됩니다.
+
 ## 종료 코드
 
 | 코드 | 동작 |

package/scripts/hooks/README.md

@@ -77,6 +77,16 @@ flowchart TB
 
 **Cost Explanation:** All hooks run locally on your machine without API calls. Only when a hook displays a message to Claude (e.g., blocking a command, suggesting compaction) does that message consume input tokens—and these messages are intentionally brief.
 
+## RTK Ordering
+
+If you opt into RTK, keep CPMM's Bash safety hook first and RTK's rewrite hook second.
+
+Recommended order in `~/.claude/settings.json`:
+- `~/.claude/scripts/hooks/critical-action-check.sh` with `timeout: 5`
+- `~/.claude/hooks/rtk-rewrite.sh` with `timeout: 10`
+
+This preserves CPMM's critical-action block before RTK rewrites the Bash command.
+
 ## Exit Codes
 
 | Code | Behavior |
@@ -115,4 +125,3 @@ Output to **stderr** is shown to Claude when blocking (exit 2). Note: stdout JSO
 2. Make executable: `chmod +x script.sh`
 3. Add to `settings.json` or agent frontmatter
 4. Test with various inputs
-