Tip

One command. Any CLI tool. Isolated sandbox.

cli-box start claude

That's it. Claude Code runs in its own sandbox window. Screenshot it. Automate it. Close it.

cli-box

macOS desktop automation sandbox for AI agents

Installation

TL;DR

You want	Run	What happens
npm	npx cli-box-skill install	Choose harness(es); binaries + skill installed
Shell	bash <(curl -fsSL https://raw.githubusercontent.com/Shadow-Azure/cli-box/main/packages/cli-box-skill/skill/install.sh) claude	Downloads to ~/.cli-box/bin/, installs skill
Manual	GitHub Releases	Download and extract manually
Upgrade	cli-box-skill upgrade	Stops sandboxes, upgrades package, preserves SKILL.md

For Humans

Paste this into Claude Code — it will download, install, configure permissions, and verify everything:

Install cli-box by following the instructions here:
https://raw.githubusercontent.com/Shadow-Azure/cli-box/main/docs/guide/installation.md

The agent handles macOS permissions, PATH setup, and a quick test run. Just approve when prompted.

For LLM Agents

Install cli-box in one command: run npx cli-box-skill install all to install the skill into every supported harness (Claude Code, OpenCode, OpenClaw), or replace all with claude / opencode / openclaw for a single target.

npx cli-box-skill install claude    # claude | opencode | openclaw | all

Upgrade

cli-box-skill upgrade            # latest
cli-box-skill upgrade 0.2.9      # specific version

Stops running sandboxes and daemon before upgrading. Your SKILL.md is preserved.

Add to PATH

echo 'export PATH="$HOME/.cli-box/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Demo

Start Claude Code in a sandbox, interact, get screenshots:

$ cli-box start claude
Sandbox started: 0cd60ad4

$ cli-box screenshot --id 0cd60ad4 -o state.png

Multi-tab — run Claude Code, OpenCode, zsh in parallel:

Works with any CLI tool:

cli-box start claude    # Claude Code
cli-box start opencode  # OpenCode
cli-box start zsh       # Shell
cli-box start node      # Node.js

Features

	What
Multi-instance	Run any CLI in its own sandbox tab
Screenshot	Window-level capture via ScreenCaptureKit, no foreground needed
PTY input	Direct terminal input, supports Chinese and all key combos
UI inspection	Read UI element tree (AX) or terminal text output
MCP integration	Claude Code / OpenCode call cli-box as an MCP tool
Zero invasion	Target app needs no adaptation — works at OS level

Quick Reference

# Sandbox lifecycle
cli-box start [command]         # Start sandbox (default: zsh)
cli-box start "cd /app && claude -r"  # Compound commands run via zsh -lc
cli-box list                    # List active sandboxes
cli-box close <id>              # Close sandbox

# Screenshot + input
cli-box screenshot --id <id> -o shot.png
cli-box screenshot --id <id> --up 100 -o history.png   # Slide window up 100 lines
cli-box screenshot --id <id> --top -o top.png          # Jump to scrollback top
cli-box scrollback --id <id>                           # Dump full session text (clean)
cli-box type --id <id> "hello world"
cli-box key --id <id> Return
cli-box click --id <id> 100 200

# UI inspection (App sandboxes: AX tree, CLI sandboxes: terminal text)
cli-box ui-inspect --id <id>                # Print UI element tree or terminal content
cli-box ui-find --id <id> --role AXButton   # Find elements by role
cli-box ui-value --id <id> --element-id 3   # Get element value by index

# MCP config (add to .claude/settings.json)
# { "mcpServers": { "cli-box": { "command": "cli-box", "args": ["mcp-serve"] } } }

How it works

• Daemon lifecycle: The daemon is started by the CLI (cli-box start). Electron detects and connects to an existing daemon; it does not auto-spawn. If you launch the Electron app directly without first running cli-box start, the app will display a "Waiting for daemon" message and poll every second.

macOS Permissions

Permission	Why	Grant in
Accessibility	Input simulation + UI inspection	System Settings → Privacy & Security
Screen Recording	Window screenshots	System Settings → Privacy & Security

Add cli-box and CLI Box.app to both lists. Permissions must be granted manually.

Tech Stack

Component	Technology
Core	Rust (≥1.88), cli-box-core
CLI	Rust, cli-box-cli binary
Desktop	Electron + React 18 + TypeScript + Vite + xterm.js
macOS APIs	CoreGraphics (CGEvent), ApplicationServices (AXUIElement), ScreenCaptureKit
License	Apache 2.0

---

中文文档 · GitHub Issues