--- name: ai-tools-setup description: 'Set up, repair, and report on the RTK+ICM+Vox AI development toolkit. Installs missing tools, fixes broken hooks and MCP config, and shows an effectiveness digest (token savings, memory accumulation, voice health) on demand or as a scheduled weekly report.' license: MIT allowed-tools: Bash, Read, Edit, Write compatibility: Claude Code on macOS (Homebrew required) metadata: targets: [_source-only] author: Oleg Koval tags: - rtk - icm - vox - setup - hooks - digest - ai-tools - productivity --- # AI Tools Setup: RTK + ICM + Vox Install, repair, and measure the RTK+ICM+Vox toolkit for Claude Code. ## What This Skill Does | Mode | When to use | |------|-------------| | **Setup** | First install on a new machine | | **Repair** | Something broke: hooks missing, MCP not loading | | **Digest** | Weekly check: token savings, memory health, voice stats | ## Tools in the Bundle | Tool | Version | Purpose | |------|---------|---------| | **RTK** | latest | Compresses CLI output by ~89% before it reaches the model | | **ICM** | latest | Persistent SQLite memory across sessions (knowledge graph + hybrid search) | | **Vox** | latest | Spoken task notifications via local TTS (zero API calls) | --- ## Step 1: Detect Current State Run this to see what is installed and what is missing: ```bash echo "=== Binary check ===" && \ (rtk --version 2>/dev/null && echo "RTK: ok") || echo "RTK: MISSING" && \ (icm --version 2>/dev/null && echo "ICM: ok") || echo "ICM: MISSING" && \ (vox --version 2>/dev/null && echo "Vox: ok") || echo "Vox: MISSING" echo "=== RTK hook ===" && \ grep -c '"rtk hook claude"' ~/.claude/settings.json 2>/dev/null \ && echo "RTK hook: ok" || echo "RTK hook: MISSING" echo "=== ICM hooks ===" && \ grep -c '"icm hook' ~/.claude/settings.json 2>/dev/null \ && echo "ICM hooks: ok" || echo "ICM hooks: MISSING" echo "=== ICM MCP ===" && \ python3 -c "import json; d=json.load(open(open('$HOME/.claude.json').name)); print('ICM MCP: ok' if 'icm' in d.get('mcpServers',{}) else 'ICM MCP: MISSING')" 2>/dev/null || echo "ICM MCP: MISSING" echo "=== Vox MCP ===" && \ python3 -c "import json; d=json.load(open(open('$HOME/.claude.json').name)); print('Vox MCP: ok' if 'vox' in d.get('mcpServers',{}) else 'Vox MCP: MISSING')" 2>/dev/null || echo "Vox MCP: MISSING" echo "=== ICM CLAUDE.md ===" && \ grep -c 'icm:start' ~/.claude/CLAUDE.md 2>/dev/null \ && echo "ICM CLAUDE.md: ok" || echo "ICM CLAUDE.md: MISSING" ``` Read the output and determine which of the following repair steps are needed. --- ## Step 2: Install Missing Binaries Only run for tools that showed MISSING above. **RTK:** ```bash brew install rtk rtk --version ``` **ICM:** ```bash brew install rtk-ai/tap/icm icm --version ``` **Vox:** ```bash brew install rtk-ai/tap/vox vox --version ``` --- ## Step 3: Repair Hooks ### RTK hook missing Add the `PreToolUse` RTK hook to `~/.claude/settings.json`. Read the file first, then add inside the existing `"hooks"` block (or create one): ```json "PreToolUse": [ { "matcher": "Bash", "hooks": [{ "type": "command", "command": "rtk hook claude" }] } ] ``` Then verify: `grep -c '"rtk hook claude"' ~/.claude/settings.json` ### ICM hooks missing Run: ```bash icm init --mode hook ``` This adds `PreToolUse`, `PostToolUse`, `PreCompact`, `UserPromptSubmit`, `SessionStart`, `SessionEnd` hooks automatically. ### Vox Stop hook missing Run: ```bash vox init --mode cli ``` --- ## Step 4: Repair MCP Servers ### ICM MCP missing ```bash icm init --mode mcp ``` ### Vox MCP missing ```bash vox init --mode mcp ``` Verify both by checking `~/.claude.json`: ```bash python3 -c "import json; d=json.load(open('$HOME/.claude.json')); print(list(d.get('mcpServers',{}).keys()))" ``` --- ## Step 5: Repair CLAUDE.md Instructions If ICM instructions are missing from `~/.claude/CLAUDE.md`: ```bash icm init --mode cli ``` Then move the block from wherever `icm init` placed it into `~/.claude/CLAUDE.md` (the global file), and remove it from any project-local files. --- ## Step 6: Effectiveness Digest Run this report to see how the toolkit is performing. Good to run weekly. ```bash echo "==============================" echo " AI TOOLS EFFECTIVENESS" echo "==============================" echo "" echo "--- RTK: Token Savings ---" rtk gain 2>/dev/null || echo "No data yet (run some commands first)" echo "" echo "--- ICM: Memory Health ---" icm health 2>/dev/null || echo "No memories yet" echo "" echo "--- ICM: Topics ---" icm topics 2>/dev/null || echo "No topics yet" echo "" echo "--- Vox: Usage ---" vox stats 2>/dev/null || echo "No stats yet" echo "" echo "==============================" ``` ### What healthy output looks like - **RTK**: `Tokens saved: 5M+ (85%+)` across `500+ commands`. If savings are low, run `rtk discover` to find uncovered commands - **ICM**: Topics like `decisions-*`, `errors-resolved`, `preferences` with recent timestamps. If empty, start storing manually with `icm store` - **Vox**: Non-zero speak count means the Stop hook fired --- ## Step 7 (Optional): Schedule a Weekly Digest To get a weekly automated report without having to remember to run this skill: ```bash # Create a weekly digest script cat > ~/ai-tools-digest.sh << 'EOF' #!/bin/bash echo "=== Weekly AI Tools Digest: $(date) ===" | tee -a ~/ai-tools-digest.log echo "" | tee -a ~/ai-tools-digest.log rtk gain 2>/dev/null | tee -a ~/ai-tools-digest.log echo "" | tee -a ~/ai-tools-digest.log icm health 2>/dev/null | tee -a ~/ai-tools-digest.log echo "" | tee -a ~/ai-tools-digest.log icm topics 2>/dev/null | tee -a ~/ai-tools-digest.log # Speak the summary if Vox is available vox "Weekly digest complete. Check your log." 2>/dev/null || true EOF chmod +x ~/ai-tools-digest.sh ``` Then set up a weekly launchd job (macOS): ```bash cat > ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist << 'EOF' Label com.oleg.ai-tools-digest ProgramArguments /bin/bash /Users/oleg.koval/ai-tools-digest.sh StartCalendarInterval Weekday 1 Hour 9 Minute 0 StandardOutPath /tmp/ai-tools-digest.log StandardErrorPath /tmp/ai-tools-digest.err EOF launchctl load ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist echo "Weekly digest scheduled for Mondays at 9am" ``` To view the digest log anytime: `cat ~/ai-tools-digest.log` To unload: `launchctl unload ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist` --- ## Quick Reference | Command | What it does | |---------|-------------| | `rtk gain` | Total tokens saved to date | | `rtk discover` | Find commands not yet covered by RTK | | `icm topics` | List all memory topic buckets | | `icm health` | Memory hygiene: stale, redundant, decay stats | | `icm recall "query"` | Search memories semantically | | `icm store -t topic -c "content" -i high` | Store a memory manually | | `vox "text"` | Speak text immediately | | `vox stats` | Usage stats for the Vox backend | | `cat ~/ai-tools-digest.log` | View scheduled digest history |