@kokorolx/ai-sandbox-wrapper 2.7.0 → 3.0.1

package/bin/cli.js

@@ -23,6 +23,7 @@ Commands:
   setup                 Run interactive setup (configure workspaces, select tools)
   update                Interactive menu to manage config (workspaces, git, networks)
   clean                 Interactive cleanup for caches/configs
+  clean cache [type]    Clear shared package caches (npm, bun, pip, playwright-browsers)
   config show [--json]         Display current global configuration
   config tool <tool> [--show]  Display host paths and config for a specific tool
 
@@ -326,9 +327,9 @@ async function runConfigTool(toolName, showContent) {
     process.exit(1);
   }
 
-  const toolHome = path.join(SANDBOX_DIR, 'tools', toolName, 'home');
+  const toolHome = path.join(SANDBOX_DIR, 'home');
   console.log(`\n🔍 Sandbox Configuration for: ${toolName}`);
-  console.log(`Host Home:  ${toolHome}`);
+  console.log(`Sandbox Home: ${toolHome}`);
 
   if (!fs.existsSync(toolHome)) {
     console.log('Status:     ⚠️  Not yet initialized (folder missing on host)');
@@ -1259,6 +1260,45 @@ async function manageNetworksMenu(rl) {
   }
 }
 
+// ============================================================================
+// CLEAN CACHE COMMAND (non-interactive)
+// ============================================================================
+const CACHE_TYPES = ['npm', 'bun', 'pip', 'playwright-browsers']
+
+function runCleanCache(cacheType) {
+  const cacheDir = path.join(SANDBOX_DIR, 'cache')
+
+  if (cacheType && !CACHE_TYPES.includes(cacheType)) {
+    console.error(`❌ Unknown cache type: ${cacheType}`)
+    console.error(`Valid types: ${CACHE_TYPES.join(', ')}`)
+    process.exit(1)
+  }
+
+  const targets = cacheType ? [cacheType] : CACHE_TYPES
+
+  let totalFreed = 0
+  for (const t of targets) {
+    const targetPath = path.join(cacheDir, t)
+    if (!pathExists(targetPath)) {
+      console.log(`  ⏭  ${t}/ (not found)`)
+      continue
+    }
+    const size = getPathSize(targetPath)
+    const sizeNum = typeof size === 'number' ? size : 0
+    try {
+      fs.rmSync(targetPath, { recursive: true, force: true })
+      fs.mkdirSync(targetPath, { recursive: true })
+      totalFreed += sizeNum
+      console.log(`  ✓ ${t}/ cleared (${formatBytes(sizeNum)})`)
+    } catch (err) {
+      const msg = err && err.message ? err.message : String(err)
+      console.error(`  ❌ ${t}/: ${msg}`)
+    }
+  }
+
+  console.log(`\n🧹 Freed ${formatBytes(totalFreed)}`)
+}
+
 // Parse subcommand and options
 const subCommand = positionalArgs[1];
 const subArg = positionalArgs[2];
@@ -1286,11 +1326,15 @@ switch (command) {
     });
     break;
   case 'clean':
-    runClean().catch((err) => {
-      const message = err && err.message ? err.message : String(err);
-      console.error('❌ Cleanup failed:', message);
-      process.exit(1);
-    });
+    if (subCommand === 'cache') {
+      runCleanCache(subArg)
+    } else {
+      runClean().catch((err) => {
+        const message = err && err.message ? err.message : String(err)
+        console.error('❌ Cleanup failed:', message)
+        process.exit(1)
+      })
+    }
     break;
   case 'config':
     if (subCommand === 'show') {

package/dockerfiles/base/Dockerfile

@@ -6,15 +6,21 @@ FROM node:22-bookworm-slim
 
 ARG AGENT_UID=1001
 
-RUN apt-get update && apt-get install -y --no-install-recommends     git     curl     ssh     ca-certificates     jq     python3     python3-pip     python3-venv     python3-dev     python3-setuptools     build-essential     libopenblas-dev     pipx     unzip     xclip     wl-clipboard     ripgrep     && curl -LsSf https://astral.sh/uv/install.sh | UV_INSTALL_DIR=/usr/local/bin sh     && rm -rf /var/lib/apt/lists/*     && pipx ensurepath
+RUN apt-get update && apt-get install -y --no-install-recommends     git     curl     ssh     ca-certificates     jq     python3     python3-pip     python3-venv     python3-dev     python3-setuptools     build-essential     libopenblas-dev     pipx     unzip     xclip     wl-clipboard     ripgrep     tmux     fd-find     sqlite3     poppler-utils     qpdf     tesseract-ocr     && curl -LsSf https://astral.sh/uv/install.sh | UV_INSTALL_DIR=/usr/local/bin sh     && rm -rf /var/lib/apt/lists/*     && pipx ensurepath
+
+# Install Python PDF processing tools for PDF skill
+RUN pip3 install --no-cache-dir --break-system-packages pypdf pdfplumber reportlab pytesseract pdf2image
 
 RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg     && chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg     && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null     && apt-get update     && apt-get install -y gh     && rm -rf /var/lib/apt/lists/*
 
+# Install bun (used by most AI tool install scripts)
+RUN npm install -g bun
+
 # Install pnpm globally using npm (not bun, for stability)
 RUN npm install -g pnpm
 
 # Install TypeScript and LSP tools using npm
-RUN npm install -g typescript typescript-language-server
+RUN npm install -g typescript typescript-language-server pyright vscode-langservers-extracted
 
 # Verify installations
 RUN node --version && npm --version && pnpm --version && tsc --version
@@ -40,6 +46,10 @@ RUN mkdir -p /usr/local/lib/openspec && \
     chmod +x /usr/local/bin/openspec
 # Install RTK - token optimizer for AI coding agents (built from source)
 COPY --from=rtk-builder /usr/local/cargo/bin/rtk /usr/local/bin/rtk
+# Install RTK OpenCode skills (auto-discovered by OpenCode agents)
+RUN mkdir -p /home/agent/.config/opencode/skills/rtk /home/agent/.config/opencode/skills/rtk-setup
+COPY skills/rtk/SKILL.md /home/agent/.config/opencode/skills/rtk/SKILL.md
+COPY skills/rtk-setup/SKILL.md /home/agent/.config/opencode/skills/rtk-setup/SKILL.md
 RUN apt-get update && apt-get install -y --no-install-recommends \
     libglib2.0-0 \
     libnspr4 \
@@ -77,7 +87,9 @@ RUN mkdir -p /opt/playwright-browsers && \
     npx playwright-core install-deps chromium && \
     chmod -R 777 /opt/playwright-browsers && \
     ln -sf $(ls -d /opt/playwright-browsers/chromium-*/chrome-linux/chrome | head -1) /opt/chromium
-RUN touch /opt/.mcp-playwright-installed
+ENV CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1
+RUN npm install -g chrome-devtools-mcp@latest && \
+    touch /opt/.mcp-chrome-devtools-installed
 
 # Create workspace
 WORKDIR /workspace

package/dockerfiles/base/skills/rtk/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: rtk
+description: "Token optimizer for AI coding agents. Wraps common CLI commands with rtk to reduce LLM token consumption by 60-90%."
+compatibility: "OpenCode with RTK binary installed"
+metadata:
+  author: Sisyphus
+  version: "1.0.0"
+---
+
+# RTK — Rust Token Killer
+
+**Purpose**: Reduce token consumption by 60-90% on shell commands. RTK filters and compresses command output before it reaches your context.
+
+## When This Skill Activates
+
+This skill is loaded automatically. Once active, **always** prefix supported commands with `rtk`.
+
+## Command Mappings (MANDATORY)
+
+When running shell commands via Bash tool, use `rtk` prefix for these commands:
+
+| Instead of | Use | Savings |
+|-----------|-----|---------|
+| `git status` | `rtk git status` | ~80% |
+| `git diff` | `rtk git diff` | ~75% |
+| `git log` | `rtk git log` | ~80% |
+| `git add/commit/push/pull` | `rtk git add/commit/push/pull` | ~90% |
+| `ls` / `ls -la` | `rtk ls` | ~80% |
+| `cat file` | `rtk read file` | ~70% |
+| `grep pattern .` | `rtk grep pattern .` | ~80% |
+| `rg pattern` | `rtk grep pattern .` | ~80% |
+| `npm test` / `cargo test` / `pytest` | `rtk test <cmd>` | ~90% |
+| `npm run build` / `cargo build` | `rtk err <cmd>` | ~80% |
+| `gh pr list/view` | `rtk gh pr list/view` | ~70% |
+| `docker ps` | `rtk docker ps` | ~80% |
+| `eslint` / `tsc` | `rtk lint` / `rtk tsc` | ~80% |
+
+## Searching Inside `node_modules` / Ignored Directories
+
+By default, `rtk grep` respects `.gitignore` rules — meaning `node_modules`, `.nuxt`, `dist`, etc. are **excluded**. This is the right behavior 99% of the time.
+
+When you **need** to search inside ignored directories (debugging a library, checking an API signature, tracing a dependency bug):
+
+```bash
+# Search all files including node_modules (--no-ignore bypasses .gitignore)
+rtk grep "defineStore" . --no-ignore
+
+# Search a specific package only (combine --no-ignore with --glob)
+rtk grep "defineStore" . --no-ignore --glob 'node_modules/pinia/**'
+```
+
+**What does NOT work:**
+- `rtk grep "pattern" node_modules/pinia/` — still excluded even with direct path
+- `rtk grep "pattern" . --glob 'node_modules/**'` — glob alone doesn't override .gitignore
+
+**Key flag: `--no-ignore`** — this is the ONLY way to search ignored directories with rtk grep.
+
+### Other useful `rtk grep` flags
+
+```bash
+rtk grep "pattern" . -t ts          # Filter by file type (ts, py, rust, etc.)
+rtk grep "pattern" . -m 100         # Increase max results (default: 50)
+rtk grep "pattern" . -u             # Ultra-compact mode (even fewer tokens)
+rtk grep "pattern" . -l 120         # Max line length before truncation (default: 80)
+```
+
+## Commands to NOT Wrap
+
+Do NOT prefix these with `rtk` (unsupported or counterproductive):
+
+- `npx`, `npm install`, `pip install` (package managers)
+- `node`, `python3`, `ruby` (interpreters)
+- `nano-brain`, `openspec`, `opencode` (custom tools)
+- Heredocs (`<<EOF`)
+- Piped commands (`cmd1 | cmd2`) — wrap only the first command if applicable
+- Commands already prefixed with `rtk`
+
+## How RTK Works
+
+```
+Without RTK:  git status → 50 lines raw output → 2,000 tokens
+With RTK:     rtk git status → "3 modified, 1 untracked ✓" → 200 tokens
+```
+
+RTK runs the real command, then filters/compresses the output. The agent sees a compact summary instead of verbose raw output.
+
+## Detection
+
+Before using RTK commands, verify it's installed:
+```bash
+rtk --version
+```
+
+If `rtk` is not found, skip this skill — run commands normally without the `rtk` prefix.
+
+## Token Savings Reference
+
+Typical 30-min coding session:
+- Without RTK: ~150,000 tokens
+- With RTK: ~45,000 tokens
+- **Savings: ~70%**
+
+Biggest wins: test output (`rtk test` — 90%), git operations (`rtk git` — 80%), file reading (`rtk read` — 70%).

package/dockerfiles/base/skills/rtk-setup/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: rtk-setup
+description: "One-time setup + ongoing enforcement of RTK (Rust Token Killer) across sessions and subagents. Persists RTK instructions to AGENTS.md and propagates to delegated tasks."
+compatibility: "OpenCode with RTK binary installed"
+metadata:
+  author: Sisyphus
+  version: "1.0.0"
+---
+
+# RTK Setup — Persistent RTK Enforcement
+
+This skill performs **setup** (persist RTK instructions) and **ongoing enforcement** (use rtk, propagate to subagents).
+
+## Phase 1: Detection (ALWAYS run first)
+
+Run these checks before anything else:
+
+```bash
+rtk --version
+```
+
+- If `rtk` is NOT found → **STOP**. Tell the user: "RTK is not installed. Install it first: `cargo install --git https://github.com/rtk-ai/rtk --locked`". Do NOT proceed with setup.
+- If `rtk` IS found → continue.
+
+### Check oh-my-opencode
+
+```bash
+ls ~/.config/opencode/oh-my-opencode.json 2>/dev/null
+```
+
+- If found → omo is installed. Note this for Phase 2.
+- If not found → skip omo-specific steps.
+
+## Phase 2: Setup (persist to AGENTS.md)
+
+Check BOTH of these files for the RTK managed block:
+
+1. **User-level**: `~/.config/opencode/AGENTS.md`
+2. **Project-level**: `./AGENTS.md` (current workspace)
+
+For EACH file, check if `<!-- RTK:START -->` exists. If it does NOT exist, **append** the following managed block to the file (create the file if it doesn't exist). NEVER replace existing content — only append.
+
+```markdown
+<!-- RTK:START -->
+<!-- Managed block - do not edit manually. Updated by: rtk-setup skill -->
+
+## RTK Token Optimizer
+
+This project uses **RTK** (Rust Token Killer) to reduce LLM token consumption by 60-90%.
+
+### Rules for ALL agents (including subagents)
+
+**ALWAYS** prefix these commands with `rtk`:
+
+| Command | Use instead |
+|---------|-------------|
+| `git status/diff/log/add/commit/push/pull` | `rtk git ...` |
+| `ls`, `ls -la` | `rtk ls` |
+| `cat file` | `rtk read file` |
+| `grep pattern .` / `rg pattern` | `rtk grep pattern .` |
+| `npm test` / `cargo test` / `pytest` | `rtk test <cmd>` |
+| `npm run build` / `cargo build` | `rtk err <cmd>` |
+| `gh pr list/view` | `rtk gh pr list/view` |
+| `docker ps` | `rtk docker ps` |
+| `eslint` / `tsc` | `rtk lint` / `rtk tsc` |
+
+**Do NOT** prefix: `npx`, `npm install`, `pip install`, `node`, `python3`, heredocs, piped commands.
+
+<!-- RTK:END -->
+```
+
+### If oh-my-opencode is installed
+
+After updating AGENTS.md files, check if the omo config at `~/.config/opencode/oh-my-opencode.json` has `prompt_append` fields on agents. If it does, inform the user:
+
+> "omo is installed. For maximum coverage, you can add RTK instructions to agent `prompt_append` fields in `oh-my-opencode.json`. This ensures subagents always use rtk even when AGENTS.md is not loaded. Want me to do this?"
+
+**Only modify `oh-my-opencode.json` if the user explicitly confirms.** If they confirm, append this line to the `prompt_append` of `sisyphus-junior` agent (the primary coder):
+
+```
+\n\nRTK: ALWAYS prefix shell commands with `rtk` when available (git, ls, grep, test, build). Example: `rtk git status` not `git status`.
+```
+
+Do NOT modify other agents' prompt_append unless asked.
+
+## Phase 3: Ongoing Enforcement (EVERY time this skill is loaded)
+
+### For the current agent
+
+From this point forward in this session, **you MUST**:
+
+1. **Use `rtk` prefix** for all supported shell commands (see table above)
+2. **Verify rtk is available** before first use: `rtk --version`
+3. If rtk is not available in the current environment, fall back to normal commands silently
+
+### For subagent delegation
+
+When delegating ANY task that involves shell commands (via `task()`, `delegate_task()`, or any delegation mechanism), **ALWAYS** add this to the `MUST DO` section of the delegation prompt:
+
+```
+- Use `rtk` prefix for shell commands when available (git, ls, grep, test, build). Run `rtk --version` first to check. If not installed, use normal commands. Examples: `rtk git status`, `rtk ls`, `rtk grep pattern .`, `rtk test npm test`.
+```
+
+This is NON-NEGOTIABLE. Subagents do not read AGENTS.md, so RTK instructions MUST be passed explicitly in every delegation prompt.
+
+### Quick reference for subagent prompts
+
+Copy-paste this one-liner into MUST DO sections:
+
+> Use `rtk` prefix for all shell commands (git, ls, grep, test, build, docker). Example: `rtk git status` not `git status`. If `rtk` is not found, use normal commands.
+
+## Summary
+
+| Phase | When | What |
+|-------|------|------|
+| Detection | Always first | Check rtk installed, check omo |
+| Setup | Once (idempotent) | Append RTK block to AGENTS.md (user + project) |
+| Enforcement | Every session | Use rtk yourself, propagate to all subagents |

package/dockerfiles/sandbox/Dockerfile

@@ -0,0 +1,133 @@
+# Build RTK from source (multi-stage: only binary is kept, Rust toolchain discarded)
+FROM rust:bookworm AS rtk-builder
+RUN cargo install --git https://github.com/rtk-ai/rtk --locked
+
+FROM node:22-bookworm-slim
+
+ARG AGENT_UID=1001
+
+RUN apt-get update && apt-get install -y --no-install-recommends     git     curl     ssh     ca-certificates     jq     python3     python3-pip     python3-venv     python3-dev     python3-setuptools     build-essential     libopenblas-dev     pipx     unzip     xclip     wl-clipboard     ripgrep     tmux     fd-find     sqlite3     poppler-utils     qpdf     tesseract-ocr     && curl -LsSf https://astral.sh/uv/install.sh | UV_INSTALL_DIR=/usr/local/bin sh     && rm -rf /var/lib/apt/lists/*     && pipx ensurepath
+
+# Install Python PDF processing tools for PDF skill
+RUN pip3 install --no-cache-dir --break-system-packages pypdf pdfplumber reportlab pytesseract pdf2image
+
+RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg     && chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg     && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null     && apt-get update     && apt-get install -y gh     && rm -rf /var/lib/apt/lists/*
+
+# Install bun (used by most AI tool install scripts)
+RUN npm install -g bun
+
+# Install pnpm globally using npm (not bun, for stability)
+RUN npm install -g pnpm
+
+# Install TypeScript and LSP tools using npm
+RUN npm install -g typescript typescript-language-server pyright vscode-langservers-extracted
+
+# Verify installations
+RUN node --version && npm --version && pnpm --version && tsc --version
+
+# Install additional tools (if selected)
+RUN PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install specify-cli --pip-args="git+https://github.com/github/spec-kit.git" && \
+    chmod +x /usr/local/bin/specify && \
+    ln -sf /usr/local/bin/specify /usr/local/bin/specify-cli
+RUN mkdir -p /usr/local/lib/uipro-cli && \
+    cd /usr/local/lib/uipro-cli && \
+    npm init -y && \
+    npm install uipro-cli && \
+    ln -sf /usr/local/lib/uipro-cli/node_modules/.bin/uipro /usr/local/bin/uipro && \
+    ln -sf /usr/local/bin/uipro /usr/local/bin/uipro-cli && \
+    chmod -R 755 /usr/local/lib/uipro-cli && \
+    chmod +x /usr/local/bin/uipro
+RUN mkdir -p /usr/local/lib/openspec && \
+    cd /usr/local/lib/openspec && \
+    npm init -y && \
+    npm install @fission-ai/openspec && \
+    ln -sf /usr/local/lib/openspec/node_modules/.bin/openspec /usr/local/bin/openspec && \
+    chmod -R 755 /usr/local/lib/openspec && \
+    chmod +x /usr/local/bin/openspec
+# Install RTK - token optimizer for AI coding agents (built from source)
+COPY --from=rtk-builder /usr/local/cargo/bin/rtk /usr/local/bin/rtk
+# Install RTK OpenCode skills (auto-discovered by OpenCode agents)
+RUN mkdir -p /home/agent/.config/opencode/skills/rtk /home/agent/.config/opencode/skills/rtk-setup
+COPY skills/rtk/SKILL.md /home/agent/.config/opencode/skills/rtk/SKILL.md
+COPY skills/rtk-setup/SKILL.md /home/agent/.config/opencode/skills/rtk-setup/SKILL.md
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libglib2.0-0 \
+    libnspr4 \
+    libnss3 \
+    libdbus-1-3 \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libcups2 \
+    libxcb1 \
+    libxkbcommon0 \
+    libatspi2.0-0 \
+    libx11-6 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxext6 \
+    libxfixes3 \
+    libxrandr2 \
+    libgbm1 \
+    libdrm2 \
+    libcairo2 \
+    libpango-1.0-0 \
+    libasound2 \
+    fonts-liberation \
+    libappindicator3-1 \
+    libu2f-udev \
+    libvulkan1 \
+    libxshmfence1 \
+    xdg-utils \
+    wget \
+    && rm -rf /var/lib/apt/lists/*
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers
+RUN mkdir -p /opt/playwright-browsers && \
+    npm install -g @playwright/mcp@latest && \
+    npx playwright-core install --no-shell chromium && \
+    npx playwright-core install-deps chromium && \
+    chmod -R 777 /opt/playwright-browsers && \
+    ln -sf $(ls -d /opt/playwright-browsers/chromium-*/chrome-linux/chrome | head -1) /opt/chromium
+ENV CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1
+RUN npm install -g chrome-devtools-mcp@latest && \
+    touch /opt/.mcp-chrome-devtools-installed
+
+# Create workspace
+WORKDIR /workspace
+
+# Non-root user for security (match host UID)
+RUN useradd -m -u ${AGENT_UID} -d /home/agent agent && \
+    mkdir -p /home/agent/.cache /home/agent/.npm /home/agent/.opencode /home/agent/.config && \
+    chown -R agent:agent /home/agent/.cache /home/agent/.npm /home/agent/.opencode /home/agent/.config /workspace && \
+    ([ -d /opt/playwright-browsers ] && chown -R agent:agent /opt/playwright-browsers || true)
+
+# === amp ===
+USER root
+RUN mkdir -p /usr/local/lib/amp && \
+    cd /usr/local/lib/amp && \
+    bun init -y && \
+    bun add @sourcegraph/amp && \
+    ln -s /usr/local/lib/amp/node_modules/.bin/amp /usr/local/bin/amp
+
+# === opencode ===
+USER root
+RUN curl -fsSL https://opencode.ai/install | bash && \
+    mv /root/.opencode/bin/opencode /usr/local/bin/opencode && \
+    rm -rf /root/.opencode
+
+# === claude ===
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends tmux && rm -rf /var/lib/apt/lists/*
+RUN npm install -g @kaitranntt/ccs --ignore-scripts && \
+    mkdir -p /home/agent/.ccs && \
+    chown -R agent:agent /home/agent/.ccs && \
+    which ccs && ccs --version && \
+    sed -i 's/fs\.symlinkSync(sourcePath, targetPath, symlinkType)/fs\.symlinkSync(require("path").relative(require("path").dirname(targetPath), sourcePath), targetPath, symlinkType)/g' /usr/local/lib/node_modules/@kaitranntt/ccs/dist/utils/claude-symlink-manager.js
+RUN export HOME=/root && curl -fsSL https://claude.ai/install.sh | bash && \
+    mkdir -p /usr/local/share && \
+    mv /root/.local/share/claude /usr/local/share/claude && \
+    ln -sf /usr/local/share/claude/versions/$(ls /usr/local/share/claude/versions | head -1) /usr/local/bin/claude
+USER agent
+
+USER agent
+ENV HOME=/home/agent
+CMD ["bash"]

package/dockerfiles/sandbox/skills/rtk/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: rtk
+description: "Token optimizer for AI coding agents. Wraps common CLI commands with rtk to reduce LLM token consumption by 60-90%."
+compatibility: "OpenCode with RTK binary installed"
+metadata:
+  author: Sisyphus
+  version: "1.0.0"
+---
+
+# RTK — Rust Token Killer
+
+**Purpose**: Reduce token consumption by 60-90% on shell commands. RTK filters and compresses command output before it reaches your context.
+
+## When This Skill Activates
+
+This skill is loaded automatically. Once active, **always** prefix supported commands with `rtk`.
+
+## Command Mappings (MANDATORY)
+
+When running shell commands via Bash tool, use `rtk` prefix for these commands:
+
+| Instead of | Use | Savings |
+|-----------|-----|---------|
+| `git status` | `rtk git status` | ~80% |
+| `git diff` | `rtk git diff` | ~75% |
+| `git log` | `rtk git log` | ~80% |
+| `git add/commit/push/pull` | `rtk git add/commit/push/pull` | ~90% |
+| `ls` / `ls -la` | `rtk ls` | ~80% |
+| `cat file` | `rtk read file` | ~70% |
+| `grep pattern .` | `rtk grep pattern .` | ~80% |
+| `rg pattern` | `rtk grep pattern .` | ~80% |
+| `npm test` / `cargo test` / `pytest` | `rtk test <cmd>` | ~90% |
+| `npm run build` / `cargo build` | `rtk err <cmd>` | ~80% |
+| `gh pr list/view` | `rtk gh pr list/view` | ~70% |
+| `docker ps` | `rtk docker ps` | ~80% |
+| `eslint` / `tsc` | `rtk lint` / `rtk tsc` | ~80% |
+
+## Searching Inside `node_modules` / Ignored Directories
+
+By default, `rtk grep` respects `.gitignore` rules — meaning `node_modules`, `.nuxt`, `dist`, etc. are **excluded**. This is the right behavior 99% of the time.
+
+When you **need** to search inside ignored directories (debugging a library, checking an API signature, tracing a dependency bug):
+
+```bash
+# Search all files including node_modules (--no-ignore bypasses .gitignore)
+rtk grep "defineStore" . --no-ignore
+
+# Search a specific package only (combine --no-ignore with --glob)
+rtk grep "defineStore" . --no-ignore --glob 'node_modules/pinia/**'
+```
+
+**What does NOT work:**
+- `rtk grep "pattern" node_modules/pinia/` — still excluded even with direct path
+- `rtk grep "pattern" . --glob 'node_modules/**'` — glob alone doesn't override .gitignore
+
+**Key flag: `--no-ignore`** — this is the ONLY way to search ignored directories with rtk grep.
+
+### Other useful `rtk grep` flags
+
+```bash
+rtk grep "pattern" . -t ts          # Filter by file type (ts, py, rust, etc.)
+rtk grep "pattern" . -m 100         # Increase max results (default: 50)
+rtk grep "pattern" . -u             # Ultra-compact mode (even fewer tokens)
+rtk grep "pattern" . -l 120         # Max line length before truncation (default: 80)
+```
+
+## Commands to NOT Wrap
+
+Do NOT prefix these with `rtk` (unsupported or counterproductive):
+
+- `npx`, `npm install`, `pip install` (package managers)
+- `node`, `python3`, `ruby` (interpreters)
+- `nano-brain`, `openspec`, `opencode` (custom tools)
+- Heredocs (`<<EOF`)
+- Piped commands (`cmd1 | cmd2`) — wrap only the first command if applicable
+- Commands already prefixed with `rtk`
+
+## How RTK Works
+
+```
+Without RTK:  git status → 50 lines raw output → 2,000 tokens
+With RTK:     rtk git status → "3 modified, 1 untracked ✓" → 200 tokens
+```
+
+RTK runs the real command, then filters/compresses the output. The agent sees a compact summary instead of verbose raw output.
+
+## Detection
+
+Before using RTK commands, verify it's installed:
+```bash
+rtk --version
+```
+
+If `rtk` is not found, skip this skill — run commands normally without the `rtk` prefix.
+
+## Token Savings Reference
+
+Typical 30-min coding session:
+- Without RTK: ~150,000 tokens
+- With RTK: ~45,000 tokens
+- **Savings: ~70%**
+
+Biggest wins: test output (`rtk test` — 90%), git operations (`rtk git` — 80%), file reading (`rtk read` — 70%).