{
  "markdown": "# can-see\n\n[![npm version](https://img.shields.io/npm/v/can-see)](https://www.npmjs.com/package/can-see)\n[![npm downloads](https://img.shields.io/npm/dm/can-see)](https://www.npmjs.com/package/can-see)\n[![license](https://img.shields.io/npm/l/can-see)](https://github.com/HurleySk/can-see/blob/master/LICENSE)\n[![node](https://img.shields.io/node/v/can-see)](https://nodejs.org)\n\nMCP server that lets AI agents **see** and **interact** with terminal/CLI applications through virtual terminals and PNG screenshots.\n\nBuilt for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and any MCP-compatible agent.\n\n## Why?\n\nSome things are easier to show than describe. When debugging a TUI app, an interactive CLI wizard, or anything with visual terminal output, `can-see` lets the agent see exactly what you see — colors, layout, cursor position, and all.\n\n## How it works\n\n1. **Launch** a CLI app in a virtual terminal ([node-pty](https://github.com/nickg/node-pty) + [@xterm/headless](https://github.com/nickg/xterm.js))\n2. **Screenshot** the terminal as a PNG image (rendered via [node-canvas](https://github.com/nickg/node-canvas))\n3. **Send keys/text** to interact with the app\n4. **Screenshot** again to see the result\n5. **Close** the session when done\n\n## Installation\n\n```bash\nnpm install -g can-see\n```\n\n### Prerequisites\n\n`can-see` depends on [node-canvas](https://github.com/nickg/node-canvas) (Cairo) and [node-pty](https://github.com/nickg/node-pty), which require native compilation. Most systems will need:\n\n- **Windows:** Visual Studio Build Tools (C++ workload) — `npm install --global windows-build-tools` or install from Visual Studio Installer\n- **macOS:** Xcode Command Line Tools — `xcode-select --install`\n- **Linux:** `sudo apt install build-essential libcairo2-dev libjpeg-dev libpango1.0-dev libgif-dev librsvg2-dev`\n\n## Configuration\n\n### Claude Code\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"can-see\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"can-see\"]\n    }\n  }\n}\n```\n\nOr if installed globally:\n\n```json\n{\n  \"mcpServers\": {\n    \"can-see\": {\n      \"command\": \"can-see\"\n    }\n  }\n}\n```\n\n### Other MCP clients\n\n`can-see` uses stdio transport. Point your MCP client at the `can-see` binary or `npx -y can-see`.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `launch` | Start a CLI app in a virtual terminal. Returns a `sessionId`. Accepts optional `env` to set environment variables. |\n| `screenshot` | Capture the terminal as a PNG image. |\n| `screenshot_region` | Capture a specific rectangular area of the terminal. |\n| `screenshot_text_region` | Find text in the viewport and capture the surrounding area as a PNG. |\n| `capture_baseline` | Snapshot terminal state for later diff comparison. |\n| `diff_screenshot` | Compare current state against baseline with highlighted changes. |\n| `get_cell_info` | Query character, colors, and attributes at specific cell(s). Supports `compact` mode for reduced output. |\n| `read_text` | Read the terminal buffer as plain text. |\n| `read_scrollback` | Read text that scrolled above the visible viewport. |\n| `wait_for_text` | Wait until specific text appears in the terminal buffer. |\n| `wait_for_idle` | Wait until terminal output has been stable for a given duration. Supports `stableMs` for content-comparison mode (for apps with timers/spinners), `excludeRows` to ignore specific rows, and `excludePattern` (regex) for dynamic row exclusion. |\n| `wait_for_color` | Wait until a specific color appears at a position. |\n| `wait_for_exit` | Wait until the process exits and return its exit code and signal. |\n| `start_recording` | Begin capturing frames for an animated GIF. |\n| `stop_recording` | Stop recording and return the animated GIF with metadata (`frameCount`, `durationMs`). Auto-trims frames or saves to file if GIF exceeds inline size limit. |\n| `send_keys` | Send keystrokes (e.g., `Enter`, `Ctrl+C`, `['Down', 'Down', 'Enter']`). |\n| `send_text` | Type a string of text into the app. |\n| `get_process_status` | Get process status — distinguish \"app is idle\" from \"app has exited\". Returns PID, running state, exit code. |\n| `list_sessions` | List all active terminal sessions. |\n| `close` | Kill the app and clean up. **Always close when done.** |\n| `close_all` | Kill all active sessions at once. Useful for cleanup between test runs. |\n\n### Supported keys\n\n`Enter`, `Tab`, `Escape`, `Backspace`, `Space`, `Up`, `Down`, `Left`, `Right`, `Home`, `End`, `Delete`, `PageUp`, `PageDown`, `Ctrl+A` through `Ctrl+Z`.\n\n## Environment variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `DEFAULT_COLS` | `120` | Terminal width in columns |\n| `DEFAULT_ROWS` | `30` | Terminal height in rows |\n| `IDLE_TIMEOUT_MS` | `300000` | Auto-close idle sessions after this many ms (5 min) |\n\n## Example usage\n\nFrom an MCP-connected agent:\n\n```\nAgent: I'll launch your app to see what's happening.\n→ launch(\"node\", [\"app.js\"])  → sessionId: \"abc-123\"\n\nAgent: Let me wait for the app to start.\n→ wait_for_text(\"abc-123\", \"Ready\")  → Found \"Ready\" after 1200ms\n\nAgent: Let me read the current output.\n→ read_text(\"abc-123\")  → \"Welcome to MyApp\\nReady\\n> \"\n\nAgent: I can see the prompt. Let me select option 2.\n→ send_keys(\"abc-123\", [\"Down\", \"Enter\"])\n\nAgent: Waiting for the screen to settle.\n→ wait_for_idle(\"abc-123\")  → Terminal idle for 520ms\n\nAgent: Let me check the result.\n→ screenshot(\"abc-123\")  → [PNG image showing result]\n\nAgent: Done, closing the session.\n→ close(\"abc-123\")\n```\n\n## Changelog\n\n### 0.5.0\n\n**New tools:**\n- `wait_for_exit` — wait for process exit, get exit code and signal\n- `close_all` — kill all active sessions at once\n- `get_process_status` — distinguish \"app is idle\" from \"app has exited\"\n- `screenshot_text_region` — find text in viewport, capture surrounding area as PNG\n\n**Enhancements:**\n- `launch` accepts `env` parameter for custom environment variables\n- `wait_for_idle` supports `excludePattern` (regex) for dynamic row exclusion in stableMs mode\n- `stop_recording` returns `frameCount` and `durationMs` metadata alongside GIF\n- `get_cell_info` supports `compact` option for reduced output (`{char, fg, bold}` only)\n\n**Bug fixes:**\n- Fixed `wait_for_text` and `wait_for_color` race condition where text/color present in the final buffer was missed when the process exited simultaneously\n- Added mutual exclusion validation when both `stableMs` and `idleMs` are passed to `wait_for_idle`\n\n## License\n\nMIT\n",
  "bytes": 6495,
  "sha": "97cd7d2604f497f0d25f5231627d0b91ed4d0f48187051d0f898c73876b02268",
  "repo_slug": "hurleysk/can-see",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hurleysk_can_see_8c13f1b0/readme"
}