ai-tools-setup

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:

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:

brew install rtk
rtk --version

ICM:

brew install rtk-ai/tap/icm
icm --version

Vox:

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):

"PreToolUse": [
  {
    "matcher": "Bash",
    "hooks": [{ "type": "command", "command": "rtk hook claude" }]
  }
]

Then verify: grep -c '"rtk hook claude"' ~/.claude/settings.json

ICM hooks missing

Run:

icm init --mode hook

This adds PreToolUse, PostToolUse, PreCompact, UserPromptSubmit, SessionStart, SessionEnd hooks automatically.

Vox Stop hook missing

Run:

vox init --mode cli

---

Step 4: Repair MCP Servers

ICM MCP missing

icm init --mode mcp

Vox MCP missing

vox init --mode mcp

Verify both by checking ~/.claude.json:

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:

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.

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:

# 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):

cat > ~/Library/LaunchAgents/com.oleg.ai-tools-digest.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.oleg.ai-tools-digest</string>
  <key>ProgramArguments</key>
  <array>
    <string>/bin/bash</string>
    <string>/Users/oleg.koval/ai-tools-digest.sh</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Weekday</key>
    <integer>1</integer>
    <key>Hour</key>
    <integer>9</integer>
    <key>Minute</key>
    <integer>0</integer>
  </dict>
  <key>StandardOutPath</key>
  <string>/tmp/ai-tools-digest.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/ai-tools-digest.err</string>
</dict>
</plist>
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