cli-box-skill 0.0.1

package/README.md

@@ -0,0 +1,39 @@
+# cli-box-skill
+
+macOS desktop automation sandbox for AI agents.
+
+## Install
+
+```bash
+npm install -g cli-box-skill
+```
+
+## What is cli-box?
+
+A macOS sandbox that lets AI agents (Claude Code, OpenCode, etc.) run CLI tools in isolated windows with screenshot feedback and input simulation.
+
+## Quick start
+
+```bash
+cli-box start claude    # Start Claude Code sandbox
+cli-box start zsh       # Start zsh sandbox
+cli-box list            # List active sandboxes
+cli-box screenshot --id <id> -o shot.png  # Screenshot
+cli-box close <id>      # Close sandbox
+```
+
+## No npm?
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/ZN-Ice/cli-box/main/skill/install.sh)
+```
+
+## Links
+
+- [GitHub](https://github.com/ZN-Ice/cli-box)
+- [Full README](https://github.com/ZN-Ice/cli-box#readme)
+- [Installation Guide](https://github.com/ZN-Ice/cli-box/blob/main/docs/guide/installation.md)
+
+## License
+
+Apache 2.0

package/bin/cli-box-wrapper.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+/**
+ * cli-box wrapper — finds the platform binary and delegates.
+ * Allows `npx cli-box` or global `cli-box` command to work.
+ */
+
+import { createRequire } from 'module';
+import { spawn } from 'child_process';
+import path from 'path';
+import os from 'os';
+
+const platform = process.platform === 'darwin' ? 'darwin' :
+                 process.platform === 'win32' ? 'win32' : 'linux';
+const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+const platformPkgName = `cli-box-${platform}-${arch}`;
+
+let binPath;
+try {
+  const require = createRequire(import.meta.url);
+  const pkgJsonPath = require.resolve(`${platformPkgName}/package.json`);
+  const pkgDir = path.dirname(pkgJsonPath);
+  binPath = path.join(pkgDir, 'bin', 'cli-box');
+} catch (e) {
+  // Fallback: check ~/.cli-box/bin/
+  binPath = path.join(os.homedir(), '.cli-box', 'bin', 'cli-box');
+}
+
+const args = process.argv.slice(2);
+const child = spawn(binPath, args, { stdio: 'inherit' });
+child.on('exit', (code) => process.exit(code ?? 1));
+child.on('error', (err) => {
+  console.error(`Failed to run cli-box: ${err.message}`);
+  console.error('Install via: npm install -g cli-box-skill');
+  console.error('Or: bash <(curl -fsSL https://raw.githubusercontent.com/ZN-Ice/cli-box/main/skill/install.sh)');
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "cli-box-skill",
+  "version": "0.0.1",
+  "description": "macOS desktop automation sandbox for AI agents",
+  "main": "postinstall.mjs",
+  "bin": {
+    "cli-box": "./bin/cli-box-wrapper.js"
+  },
+  "scripts": {
+    "postinstall": "node postinstall.mjs"
+  },
+  "optionalDependencies": {
+    "cli-box-darwin-arm64": "0.0.1",
+    "cli-box-electron-darwin-arm64": "0.0.1"
+  },
+  "files": [
+    "skill/SKILL.md",
+    "skill/install.sh",
+    "postinstall.mjs",
+    "bin/",
+    "README.md"
+  ],
+  "keywords": [
+    "cli-box",
+    "macos",
+    "automation",
+    "sandbox",
+    "claude-code",
+    "opencode",
+    "skill",
+    "desktop",
+    "screenshot"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZN-Ice/cli-box.git"
+  },
+  "author": "ZN-Ice",
+  "license": "Apache-2.0"
+}

package/postinstall.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+/**
+ * cli-box postinstall script
+ *
+ * Runs after `npm install -g cli-box-skill`.
+ * 1. Finds the installed platform package (cli-box-darwin-arm64)
+ * 2. Creates symlinks in ~/.cli-box/bin/
+ * 3. Installs SKILL.md to .claude/skills/cli-box/ and .opencode/skills/cli-box/
+ */
+
+import { createRequire } from 'module';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const home = os.homedir();
+const binDir = path.join(home, '.cli-box', 'bin');
+
+function info(msg) { console.log(`  ➜  ${msg}`); }
+function ok(msg) { console.log(`  ✓  ${msg}`); }
+function warn(msg) { console.warn(`  ⚠  ${msg}`); }
+
+// 1. Detect platform
+const platform = process.platform === 'darwin' ? 'darwin' :
+                 process.platform === 'win32' ? 'win32' : 'linux';
+const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+const platformPkgName = `cli-box-${platform}-${arch}`;
+
+info(`Platform: ${platform}-${arch}`);
+
+// 2. Find platform package
+let platformPkgDir;
+try {
+  const require = createRequire(import.meta.url);
+  const pkgJsonPath = require.resolve(`${platformPkgName}/package.json`);
+  platformPkgDir = path.dirname(pkgJsonPath);
+  ok(`Found platform package: ${platformPkgName}`);
+} catch (e) {
+  warn(`Platform package ${platformPkgName} not found. Skipping binary setup.`);
+  warn('You can install binaries manually via: bash <(curl -fsSL https://raw.githubusercontent.com/ZN-Ice/cli-box/main/skill/install.sh)');
+  process.exit(0);
+}
+
+// 3. Create symlinks
+try {
+  fs.mkdirSync(binDir, { recursive: true });
+
+  const bins = ['cli-box', 'cli-box-daemon'];
+  for (const bin of bins) {
+    const src = path.join(platformPkgDir, 'bin', bin);
+    const dst = path.join(binDir, bin);
+
+    if (fs.existsSync(src)) {
+      fs.rmSync(dst, { force: true });
+      fs.symlinkSync(src, dst);
+      fs.chmodSync(src, 0o755);
+      ok(`${bin} → ${src}`);
+    } else {
+      warn(`${bin} not found in platform package`);
+    }
+  }
+} catch (e) {
+  warn(`Failed to create symlinks: ${e.message}`);
+}
+
+// 4. Install SKILL.md
+const skillSrc = path.join(path.dirname(new URL(import.meta.url).pathname), 'skill', 'SKILL.md');
+
+const targets = [
+  path.join(home, '.claude', 'skills', 'cli-box'),
+  path.join(home, '.config', 'opencode', 'skills', 'cli-box'),
+];
+
+for (const target of targets) {
+  try {
+    if (fs.existsSync(path.dirname(target))) {
+      fs.mkdirSync(target, { recursive: true });
+      fs.copyFileSync(skillSrc, path.join(target, 'SKILL.md'));
+      ok(`SKILL.md → ${target}/`);
+    }
+  } catch (e) {
+    // Silent — target harness may not be installed
+  }
+}
+
+// 5. Done
+console.log('');
+console.log('  cli-box installed successfully!');
+console.log('');
+console.log('  Add to PATH:');
+console.log(`    export PATH="$HOME/.cli-box/bin:$PATH"`);
+console.log('');
+console.log('  Quick start:');
+console.log('    cli-box start claude');
+console.log('    cli-box start zsh');
+console.log('    cli-box list');
+console.log('');

package/skill/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: cli-box
+description: macOS desktop automation sandbox — run CLI tools and macOS apps in isolated sandbox windows with screenshot feedback and input simulation
+---
+
+# cli-box
+
+macOS desktop automation sandbox. Launch isolated sandbox windows from the CLI, run any CLI tool (Claude Code, OpenCode, zsh, etc.) inside them, and automate via screenshot + keyboard/mouse simulation.
+
+## Prerequisites
+
+- macOS 14.0+ (Sonoma), Apple Silicon or Intel
+- **Accessibility** permission (System Settings → Privacy & Security → Accessibility)
+- **Screen Recording** permission (System Settings → Privacy & Security → Screen Recording)
+
+Both permissions must be granted manually. Add `cli-box` and `CLI Box.app` to both lists.
+
+## Installation
+
+```bash
+npm install -g cli-box-skill
+```
+
+Or via GitHub Release:
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/ZN-Ice/cli-box/main/skill/install.sh)
+```
+
+## Quick Start
+
+```bash
+# Start a sandbox running Claude Code
+cli-box start claude
+
+# Start a sandbox running zsh
+cli-box start zsh
+
+# List all active sandboxes
+cli-box list
+
+# Take a screenshot of a sandbox
+cli-box screenshot --id <sandbox-id> -o screenshot.png
+
+# Type text into a sandbox (PTY mode for CLI tools)
+cli-box type --id <sandbox-id> --pty "hello world"
+
+# Press Enter to send
+cli-box key --id <sandbox-id> --pty Return
+
+# Close a sandbox
+cli-box close <sandbox-id>
+```
+
+## Commands
+
+### Sandbox Management
+
+| Command | Description |
+|---------|-------------|
+| `cli-box start [command]` | Start sandbox (default: zsh). Supports `claude`, `opencode`, `zsh`, `bash`, or any CLI |
+| `cli-box start /path/to/App.app` | Start sandbox with a macOS application |
+| `cli-box start claude -- -p "question"` | Start sandbox with arguments |
+| `cli-box list` | List all active sandboxes with ID, title, status, port |
+| `cli-box close <id>` | Close a sandbox and clean up |
+| `cli-box inspect <id>` | Show sandbox details |
+
+### Input Simulation
+
+| Command | Description |
+|---------|-------------|
+| `cli-box type --id <id> --pty "text"` | Type text via PTY (recommended for CLI tools) |
+| `cli-box key --id <id> --pty Return` | Press a key via PTY |
+| `cli-box key --id <id> --pty ctrl+c` | Send Ctrl+C |
+| `cli-box key --id <id> --pty up` | Arrow keys |
+| `cli-box click --id <id> 100 200` | Mouse click at coordinates (CGEvent) |
+
+### Screenshots
+
+| Command | Description |
+|---------|-------------|
+| `cli-box screenshot --id <id>` | Screenshot to stdout (base64) |
+| `cli-box screenshot --id <id> -o file.png` | Screenshot to file |
+
+### MCP Integration
+
+Add to `.claude/settings.json` or `.opencode/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cli-box": {
+      "command": "cli-box",
+      "args": ["mcp-serve"]
+    }
+  }
+}
+```
+
+Then use tools: `start_sandbox`, `screenshot`, `click`, `type_text`, `press_key`, `close_sandbox`, `list_sandboxes`.
+
+## Typical Workflow
+
+```bash
+# 1. Start sandbox
+cli-box start claude
+# → Returns: Sandbox started: abc123
+
+# 2. Wait for tool to initialize
+sleep 10
+
+# 3. Screenshot to see current state
+cli-box screenshot --id abc123 -o state.png
+
+# 4. Interact
+cli-box type --id abc123 --pty "Write a hello world function"
+cli-box key --id abc123 --pty Return
+
+# 5. Wait and screenshot again
+sleep 15
+cli-box screenshot --id abc123 -o result.png
+
+# 6. Clean up
+cli-box close abc123
+```
+
+## Notes
+
+- CLI tools (claude, opencode, zsh) should always use `--pty` mode for input
+- CGEvent mode (no `--pty`) is for GUI app sandboxes only
+- Each sandbox gets its own Electron tab and HTTP port
+- The daemon auto-starts on first `cli-box start` and manages all sandboxes

package/skill/install.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# cli-box skill installer
+# Downloads binaries from GitHub Release and sets up skill files
+
+REPO="ZN-Ice/cli-box"
+VERSION="${CLI_BOX_VERSION:-latest}"
+INSTALL_DIR="$HOME/.cli-box/bin"
+SKILL_CLAUDE_DIR="$HOME/.claude/skills/cli-box"
+SKILL_OPENCODE_DIR="$HOME/.config/opencode/skills/cli-box"
+
+info()  { echo "  ➜  $*"; }
+ok()    { echo "  ✓  $*"; }
+err()   { echo "  ✗  $*" >&2; exit 1; }
+
+echo ""
+echo "=============================================="
+echo " cli-box — Skill Installer"
+echo "=============================================="
+echo ""
+
+# Check prerequisites
+if ! command -v curl &>/dev/null; then
+    err "curl not found — please install curl"
+fi
+
+if [[ "$(uname)" != "Darwin" ]]; then
+    err "cli-box only supports macOS"
+fi
+
+# Determine version
+if [ "$VERSION" = "latest" ]; then
+    info "Fetching latest release version..."
+    VERSION=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" | grep '"tag_name"' | sed 's/.*"tag_name": *"//' | sed 's/".*//')
+    if [ -z "$VERSION" ]; then
+        err "Failed to fetch latest version"
+    fi
+fi
+ok "Version: $VERSION"
+
+# Download skill tarball
+info "Downloading cli-box-skill.tar.gz..."
+TMPDIR=$(mktemp -d)
+trap 'rm -rf "$TMPDIR"' EXIT
+
+DOWNLOAD_URL="https://github.com/$REPO/releases/download/$VERSION/cli-box-skill.tar.gz"
+if ! curl -fsSL "$DOWNLOAD_URL" -o "$TMPDIR/cli-box-skill.tar.gz"; then
+    err "Failed to download from $DOWNLOAD_URL"
+fi
+ok "Downloaded"
+
+# Extract
+info "Extracting..."
+tar xzf "$TMPDIR/cli-box-skill.tar.gz" -C "$TMPDIR"
+
+# Install binaries
+info "Installing binaries to $INSTALL_DIR..."
+mkdir -p "$INSTALL_DIR"
+cp "$TMPDIR/bin/cli-box" "$INSTALL_DIR/"
+cp "$TMPDIR/bin/cli-box-daemon" "$INSTALL_DIR/"
+chmod +x "$INSTALL_DIR/cli-box" "$INSTALL_DIR/cli-box-daemon"
+ok "Binaries installed"
+
+# Install skill to Claude Code
+if [ -d "$(dirname "$SKILL_CLAUDE_DIR")" ]; then
+    info "Installing skill to Claude Code..."
+    mkdir -p "$SKILL_CLAUDE_DIR"
+    cp "$TMPDIR/SKILL.md" "$SKILL_CLAUDE_DIR/"
+    ok "Skill installed to $SKILL_CLAUDE_DIR"
+fi
+
+# Install skill to OpenCode
+if [ -d "$(dirname "$SKILL_OPENCODE_DIR")" ]; then
+    info "Installing skill to OpenCode..."
+    mkdir -p "$SKILL_OPENCODE_DIR"
+    cp "$TMPDIR/SKILL.md" "$SKILL_OPENCODE_DIR/"
+    ok "Skill installed to $SKILL_OPENCODE_DIR"
+fi
+
+# Check PATH
+if [[ ":$PATH:" != *":$INSTALL_DIR:"* ]]; then
+    echo ""
+    info "Add to your PATH:"
+    echo "  export PATH=\"\$HOME/.cli-box/bin:\$PATH\""
+    echo ""
+    info "Add to ~/.zshrc or ~/.bashrc for persistence."
+fi
+
+# Verify
+echo ""
+info "Verifying installation..."
+if "$INSTALL_DIR/cli-box" --version &>/dev/null; then
+    ok "cli-box installed: $($INSTALL_DIR/cli-box --version 2>&1 || echo 'ok')"
+else
+    ok "cli-box binary installed (version check requires daemon)"
+fi
+
+echo ""
+echo "=============================================="
+echo " Installation complete!"
+echo ""
+echo " Quick start:"
+echo "   cli-box start claude    # Start Claude Code sandbox"
+echo "   cli-box start zsh       # Start zsh sandbox"
+echo "   cli-box list            # List active sandboxes"
+echo ""
+echo " Permissions required:"
+echo "   System Settings → Privacy & Security → Accessibility"
+echo "   System Settings → Privacy & Security → Screen Recording"
+echo "=============================================="
+echo ""