oh-my-customcodex 0.1.0

package/templates/.claude/skills/rtk-exec/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: rtk-exec
+description: Execute CLI commands through RTK proxy for token-optimized output
+scope: core
+argument-hint: "<command> [args...] [--gain] [--version] [--init]"
+user-invocable: true
+---
+
+# RTK Exec Skill
+
+Execute CLI commands through the RTK (Rust Token Killer) proxy to reduce LLM token consumption by 60-90%. RTK is a CLI command proxy — it wraps existing shell commands and compresses their output using smart filtering, grouping, truncation, and deduplication.
+
+> **Important**: RTK is NOT an AI prompt tool. It is a CLI output compressor. You pass it a regular shell command and it returns compressed output.
+
+## Options
+
+```
+<command> [args...]   Required. CLI command to proxy through RTK (e.g., "ls .", "git status", "cargo test")
+--gain               Show token savings statistics (rtk gain)
+--version            Show RTK version (rtk --version)
+--init               Initialize RTK for current project (rtk init -g)
+--timeout <ms>       Execution timeout (default: 120000, max: 600000)
+--working-dir <dir>  Working directory for command execution
+```
+
+## Workflow
+
+```
+1. Pre-checks
+   - Verify `rtk` binary is installed (which rtk)
+   - No authentication required
+2. Build command
+   - Special: rtk gain | rtk --version | rtk init -g
+   - Proxy: rtk <command> [args...]
+3. Execute
+   - Run via Bash tool with timeout (default 2min, max 10min)
+   - Or use helper script: node .codex/skills/rtk-exec/scripts/rtk-wrapper.cjs
+4. Parse output
+   - RTK always returns plain text compressed output (no JSON modes)
+   - Capture stdout and stderr
+5. Report results
+   - Format output with execution metadata and token savings info
+```
+
+## Supported Commands
+
+RTK supports 100+ CLI commands across categories:
+
+| Category | Commands |
+|----------|----------|
+| File ops | `ls`, `find`, `grep`, `cat`, `tree`, `du`, `diff` |
+| Git | `git status`, `git log`, `git diff`, `git push`, `git pull`, `git branch` |
+| Test runners | `cargo test`, `pytest`, `vitest`, `jest`, `go test`, `bun test` |
+| Linters | `eslint`, `tsc`, `ruff`, `clippy`, `golangci-lint`, `rubocop` |
+| Package managers | `pnpm install`, `pip install`, `cargo build`, `npm install` |
+| Containers | `docker build`, `docker ps`, `kubectl get`, `kubectl logs` |
+| Build tools | `make`, `cmake`, `gradle`, `mvn` |
+| System | `ps`, `top`, `df`, `netstat`, `env` |
+
+## Output Format
+
+### Success
+```
+[RTK Exec] Completed
+
+Command: rtk git status
+Duration: 0.3s
+Working Dir: /path/to/project
+
+--- Output ---
+{rtk compressed output}
+```
+
+### Success (--gain)
+```
+[RTK Exec] Token Savings
+
+--- Gain Report ---
+{rtk gain statistics showing tokens saved per command}
+```
+
+### Failure
+```
+[RTK Exec] Failed
+
+Command: rtk cargo test
+Error: {error_message}
+Exit Code: {code}
+Stderr: {stderr}
+Suggested Fix: {suggestion}
+```
+
+## Helper Script
+
+For complex executions or programmatic use:
+```bash
+node .codex/skills/rtk-exec/scripts/rtk-wrapper.cjs --command "cargo test" [options]
+```
+
+The wrapper provides:
+- Binary availability check
+- Safe command construction
+- Timeout handling with graceful SIGTERM → SIGKILL escalation
+- Structured JSON output for programmatic consumption
+
+## Examples
+
+```bash
+# List files with compression
+/rtk-exec "ls -la src/"
+
+# Git status (often 70%+ token reduction)
+/rtk-exec "git status"
+
+# Run Rust tests
+/rtk-exec "cargo test"
+
+# Run Python tests
+/rtk-exec "pytest tests/ -v"
+
+# TypeScript type check
+/rtk-exec "tsc --noEmit"
+
+# Show token savings stats
+/rtk-exec --gain
+
+# Initialize RTK for project
+/rtk-exec --init
+
+# With timeout override
+/rtk-exec "cargo build --release" --timeout 300000
+
+# Specify working directory
+/rtk-exec "git log --oneline -20" --working-dir /path/to/repo
+```
+
+## Integration
+
+Works with the orchestrator pattern:
+- Main conversation delegates CLI execution via this skill
+- Results are returned to the main conversation for further processing
+- Particularly effective for test runs, lint checks, and git operations where output is verbose
+- Can be chained: rtk-exec for output collection → Claude expert for analysis
+
+## Availability Check
+
+rtk-exec requires the RTK binary to be installed. The skill is only usable when:
+
+1. `rtk` binary is found in PATH (`which rtk` succeeds)
+2. No authentication or API keys required
+
+If the binary check fails, this skill cannot be used. Fall back to direct Bash tool execution.
+
+> **Note**: This skill is invoked via `/rtk-exec` command or delegated by the orchestrator. It is most useful for any task that produces verbose CLI output that would otherwise consume large amounts of context tokens.
+
+## Agent Teams Integration
+
+When used within Agent Teams:
+
+1. **As delegated task**: orchestrator explicitly delegates CLI execution for token-efficient output
+2. **Hybrid workflow**: Claude team member plans → rtk-exec runs commands → Claude analyzes compressed output
+3. **Batch execution**: Multiple rtk-exec invocations in parallel for different commands
+
+```
+Orchestrator delegates CLI task
+  → /rtk-exec invoked with command
+  → Compressed output returned to orchestrator
+  → Analyst processes compressed result
+  → Iterate if needed
+```
+
+## Token Savings
+
+RTK uses four compression strategies:
+
+| Strategy | Description | Typical Savings |
+|----------|-------------|-----------------|
+| Smart Filtering | Removes redundant/noise lines based on command type | 30-50% |
+| Grouping | Collapses repeated patterns into summary counts | 20-40% |
+| Truncation | Clips excessively long lines with ellipsis | 10-20% |
+| Deduplication | Removes identical repeated output blocks | 15-30% |
+
+Combined effect: **60-90% token reduction** on typical CLI output (git log, test results, lint reports).
+
+## Installation
+
+```bash
+# macOS via Homebrew
+brew install rtk
+
+# Universal install script
+curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
+
+# From source via Cargo
+cargo install --git https://github.com/rtk-ai/rtk
+
+# Verify installation
+rtk --version
+```

package/templates/.claude/skills/rtk-exec/scripts/rtk-wrapper.cjs

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+
+/**
+ * rtk-wrapper.cjs
+ *
+ * Node.js wrapper for RTK (Rust Token Killer) CLI proxy.
+ * Executes shell commands through RTK for token-optimized compressed output.
+ *
+ * Usage:
+ *   node rtk-wrapper.cjs --command "git status" [options]
+ *   node rtk-wrapper.cjs --gain
+ *   node rtk-wrapper.cjs --version
+ *   node rtk-wrapper.cjs --init
+ *
+ * Options:
+ *   --command <cmd>       Required (unless --gain/--version/--init): CLI command to proxy through RTK
+ *   --timeout <ms>        Execution timeout in milliseconds (default: 120000, max: 600000)
+ *   --working-dir <dir>   Set working directory for execution
+ *   --gain                Show token savings statistics (rtk gain)
+ *   --version             Show RTK version (rtk --version)
+ *   --init                Initialize RTK for current project (rtk init -g)
+ *
+ * Output (JSON to stdout):
+ *   Success: { "success": true, "output": "...", "duration_ms": 1234, "command": "..." }
+ *   Failure: { "success": false, "error": "...", "stderr": "...", "exit_code": 1 }
+ *
+ * Exit codes:
+ *   0 = success
+ *   1 = execution error
+ *   2 = validation error (missing binary or invalid arguments)
+ */
+
+const { spawn, execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Configuration
+const DEFAULT_TIMEOUT_MS = 120000; // 2 minutes
+const MAX_TIMEOUT_MS = 600000; // 10 minutes
+const KILL_GRACE_PERIOD_MS = 5000; // 5 seconds for graceful shutdown
+
+/**
+ * Parse command line arguments
+ * @returns {Object} Parsed arguments
+ */
+function parseArgs() {
+  const args = {
+    command: null,
+    timeout: DEFAULT_TIMEOUT_MS,
+    workingDir: null,
+    gain: false,
+    version: false,
+    init: false,
+  };
+
+  for (let i = 2; i < process.argv.length; i++) {
+    const arg = process.argv[i];
+
+    switch (arg) {
+      case '--command':
+        if (i + 1 < process.argv.length) {
+          args.command = process.argv[++i];
+        }
+        break;
+      case '--timeout':
+        if (i + 1 < process.argv.length) {
+          const timeoutValue = parseInt(process.argv[++i], 10);
+          if (!isNaN(timeoutValue)) {
+            args.timeout = Math.min(timeoutValue, MAX_TIMEOUT_MS);
+          }
+        }
+        break;
+      case '--working-dir':
+        if (i + 1 < process.argv.length) {
+          args.workingDir = process.argv[++i];
+        }
+        break;
+      case '--gain':
+        args.gain = true;
+        break;
+      case '--version':
+        args.version = true;
+        break;
+      case '--init':
+        args.init = true;
+        break;
+    }
+  }
+
+  return args;
+}
+
+/**
+ * Validate environment for RTK execution
+ * No auth required — only checks binary availability
+ * @returns {Object} Validation result { valid: boolean, errors: string[], rtkPath: string|null }
+ */
+function validateEnvironment() {
+  const errors = [];
+  let rtkPath = null;
+
+  // Check for rtk binary
+  try {
+    const result = execFileSync('which', ['rtk'], { stdio: 'pipe' });
+    rtkPath = result.toString().trim();
+  } catch (error) {
+    // Try common installation paths
+    const commonPaths = [
+      '/usr/local/bin/rtk',
+      path.join(os.homedir(), '.local', 'bin', 'rtk'),
+      path.join(os.homedir(), 'bin', 'rtk'),
+      path.join(os.homedir(), '.cargo', 'bin', 'rtk'),
+      '/opt/homebrew/bin/rtk',
+    ];
+
+    const foundPath = commonPaths.find(p => fs.existsSync(p));
+    if (foundPath) {
+      rtkPath = foundPath;
+    } else {
+      errors.push(
+        'rtk binary not found in PATH or common locations. ' +
+        'Install with: brew install rtk, ' +
+        'curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh, ' +
+        'or cargo install --git https://github.com/rtk-ai/rtk'
+      );
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    rtkPath,
+  };
+}
+
+/**
+ * Build RTK command array
+ * @param {Object} options - Parsed arguments
+ * @returns {Object} Command structure { binary: string, args: string[], label: string }
+ */
+function buildCommand(options) {
+  // Special commands
+  if (options.gain) {
+    return { binary: 'rtk', args: ['gain'], label: 'rtk gain' };
+  }
+
+  if (options.version) {
+    return { binary: 'rtk', args: ['--version'], label: 'rtk --version' };
+  }
+
+  if (options.init) {
+    return { binary: 'rtk', args: ['init', '-g'], label: 'rtk init -g' };
+  }
+
+  // Proxy command: rtk <command_parts...>
+  // Split the command string into parts for safe argv construction
+  const commandParts = splitCommand(options.command);
+  return {
+    binary: 'rtk',
+    args: commandParts,
+    label: `rtk ${options.command}`,
+  };
+}
+
+/**
+ * Split a command string into argv parts, respecting quoted strings
+ * Simple shell-like splitting (no full POSIX parsing)
+ * @param {string} cmd - Command string
+ * @returns {string[]} Argv parts
+ */
+function splitCommand(cmd) {
+  const parts = [];
+  let current = '';
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+
+  for (let i = 0; i < cmd.length; i++) {
+    const ch = cmd[i];
+
+    if (ch === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+    } else if (ch === '"' && !inSingleQuote) {
+      inDoubleQuote = !inDoubleQuote;
+    } else if (ch === ' ' && !inSingleQuote && !inDoubleQuote) {
+      if (current.length > 0) {
+        parts.push(current);
+        current = '';
+      }
+    } else {
+      current += ch;
+    }
+  }
+
+  if (current.length > 0) {
+    parts.push(current);
+  }
+
+  return parts;
+}
+
+/**
+ * Execute RTK command
+ * @param {string} binary - Binary to execute (rtk)
+ * @param {string[]} args - Command arguments
+ * @param {number} timeout - Timeout in milliseconds
+ * @param {string|null} workingDir - Working directory
+ * @returns {Promise<Object>} Execution result
+ */
+function executeRtk(binary, args, timeout, workingDir = null) {
+  return new Promise((resolve) => {
+    const startTime = Date.now();
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+
+    const spawnOptions = {
+      cwd: workingDir || process.cwd(),
+      env: process.env,
+    };
+
+    const child = spawn(binary, args, spawnOptions);
+
+    // Collect output
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    // Set timeout
+    const timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      console.error('[rtk-wrapper] Timeout reached, terminating process...');
+
+      // Graceful termination attempt
+      child.kill('SIGTERM');
+
+      // Force kill after grace period
+      setTimeout(() => {
+        if (!child.killed) {
+          console.error('[rtk-wrapper] Force killing process...');
+          child.kill('SIGKILL');
+        }
+      }, KILL_GRACE_PERIOD_MS);
+    }, timeout);
+
+    // Handle process exit
+    child.on('close', (exitCode) => {
+      clearTimeout(timeoutHandle);
+      const durationMs = Date.now() - startTime;
+
+      resolve({
+        exitCode: exitCode !== null ? exitCode : 1,
+        stdout,
+        stderr,
+        timedOut,
+        durationMs,
+      });
+    });
+
+    // Handle spawn errors
+    child.on('error', (error) => {
+      clearTimeout(timeoutHandle);
+      const durationMs = Date.now() - startTime;
+
+      resolve({
+        exitCode: 1,
+        stdout,
+        stderr: stderr + '\nSpawn error: ' + error.message,
+        timedOut: false,
+        durationMs,
+      });
+    });
+  });
+}
+
+/**
+ * Main execution function
+ */
+async function main() {
+  const args = parseArgs();
+
+  // Determine which mode we're running in
+  const isSpecialCommand = args.gain || args.version || args.init;
+
+  // Validate required arguments
+  if (!isSpecialCommand && !args.command) {
+    const result = {
+      success: false,
+      error: 'Missing required argument: --command (or use --gain, --version, --init)',
+      exit_code: 2,
+    };
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(2);
+  }
+
+  // Validate environment (binary check only, no auth)
+  const validation = validateEnvironment();
+  if (!validation.valid) {
+    const result = {
+      success: false,
+      error: 'RTK binary not found',
+      validation_errors: validation.errors,
+      exit_code: 2,
+    };
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(2);
+  }
+
+  console.error(`[rtk-wrapper] RTK binary: ${validation.rtkPath}`);
+  console.error(`[rtk-wrapper] Executing with timeout: ${args.timeout}ms`);
+  if (args.workingDir) {
+    console.error(`[rtk-wrapper] Working directory: ${args.workingDir}`);
+  }
+
+  // Build command
+  const command = buildCommand(args);
+  console.error(`[rtk-wrapper] Command: ${command.binary} ${command.args.join(' ')}`);
+
+  // Execute
+  const execResult = await executeRtk(
+    command.binary,
+    command.args,
+    args.timeout,
+    args.workingDir
+  );
+
+  // Determine success
+  const success = execResult.exitCode === 0 && !execResult.timedOut;
+
+  // Build result object
+  const result = {
+    success,
+    duration_ms: execResult.durationMs,
+    exit_code: execResult.exitCode,
+    command: command.label,
+  };
+
+  if (success) {
+    result.output = execResult.stdout.trim();
+    if (execResult.stderr.trim()) {
+      result.stderr = execResult.stderr.trim();
+    }
+  } else {
+    if (execResult.timedOut) {
+      result.error = `Execution timed out after ${args.timeout}ms`;
+    } else {
+      result.error = 'Execution failed';
+    }
+    if (execResult.stderr.trim()) {
+      result.stderr = execResult.stderr.trim();
+    }
+    if (execResult.stdout.trim()) {
+      result.partial_output = execResult.stdout.trim();
+    }
+  }
+
+  // Output JSON result to stdout
+  console.log(JSON.stringify(result, null, 2));
+
+  process.exit(result.exit_code);
+}
+
+// Run
+main().catch(error => {
+  const result = {
+    success: false,
+    error: 'Unexpected error: ' + error.message,
+    stack: error.stack,
+    exit_code: 1,
+  };
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(1);
+});