Claws

Your AI just got terminal superpowers.

The Problem → The Solution

Before Claws: copy a command from Claude → paste in terminal → copy the output → paste it back → repeat 47 times. One terminal. No visibility. No parallelism.

After Claws: your AI controls every terminal directly. Spawns workers. Runs tests, builds, deploys — all in parallel, all visible. You just watch.

Get Started in 3 Steps

Step 1 — Install into your project

From the project root, paste this into any terminal:

bash <(curl -fsSL https://raw.githubusercontent.com/neunaha/claws/main/scripts/install.sh)

The installer is project-local — it writes .mcp.json, .claws-bin/mcp_server.js, and .claude/{commands,rules,skills}/ into the project you're in. Each project gets its own configurable Claws setup. Re-run it in any other project to enable Claws there.

Zero runtime dependencies. Just Node.js (ships with VS Code). The extension is built from TypeScript on install; node-pty is an optional native dep with a pure-Node fallback.

Step 2 — Reload VS Code

Cmd+Shift+P → Developer: Reload Window

Step 3 — Restart Claude Code in this project

Exit your current Claude Code session and re-open claude from the project root so it picks up the project-local .mcp.json and registers the 14 Claws tools (8 terminal-control + 6 claws/2 multi-agent). If the tools don't appear, run /claws-fix.

Step 4 — You're ready

Type /claws to see the dashboard. Type /claws-do run my tests to see it work.

What You'll See

After install, your VS Code terminal panel transforms:

• CLAWS banner appears in every new terminal with live bridge status
• "Claws Wrapped Terminal" appears in the terminal dropdown — click it for full pty capture
• Multiple worker tabs appear when AI spawns parallel terminals
• Shell commands (claws-ls, claws-new, claws-run, claws-log) work in any terminal

The Commands

One command to remember: /claws

Talk naturally — examples:

/claws-do run my tests                              → single terminal, runs tests, reports
/claws-do lint test and build in parallel            → 3 terminals, all running simultaneously
/claws-go fix the bug in auth.ts                     → spawns a Claude worker to fix it
/claws-go audit this codebase for security issues    → spawns a Claude worker to audit
/claws-watch                                          → shows all terminals + their latest output
/claws-cleanup                                        → closes all worker terminals

How It Works

Claws runs a socket server inside VS Code. Any process connects and controls terminals via JSON commands.

Wrapped terminals are the key feature — as of v0.4 they use VS Code's native Pseudoterminal API (backed by node-pty, with a child_process pipe-mode fallback). No script(1) wrapping means zero rendering corruption for TUI apps like Claude Code, vim, htop, k9s. Every byte the shell emits flows through the extension's own onDidWrite event and into an in-memory ring buffer — readable via readLog with ANSI escapes stripped, giving you clean text of everything that happened.

A status bar item (right side, $(terminal) Claws (N)) shows live socket + terminal count at a glance; click it to run Health Check. Color shifts to warning-yellow in pipe-mode and error-red when no server is running.

Capabilities

Terminal Management

List all terminals with PID, name, status. Create new ones with custom names. Focus, show, close programmatically. Every terminal gets a stable numeric ID.

Full Pty Capture

Read back anything — Claude Code conversations, vim sessions, build logs, REPL outputs. The terminal looks and behaves normally. The capture layer is invisible.

Command Execution

Run commands with captured stdout + stderr + exit code. File-based capture works in every terminal type without shell integration.

Safety Gate

Detects TUI vs shell. Warns before sending text into vim/claude instead of a shell prompt. Non-blocking by default.

Self-Diagnosis & Cleanup

Every install ships with a first-class diagnostic surface — no external tools, no guesswork.

• Status bar item — live $(terminal) Claws (N) with socket + node-pty state in the tooltip. Click to run Health Check. Warning-yellow in pipe-mode, error-red when no server is running.
• Health Check (cmd+alt+c h / palette → Claws: Health Check) — one-shot introspection snapshot: extension version, Node + Electron ABI, platform, node-pty load path (or fallback reason), every active socket, MCP server version, uptime.
• Show Log (cmd+alt+c l) — focuses the Claws Output channel with the full runtime trace.
• Show Status (cmd+alt+c s) — markdown-formatted runtime block, copy-pasteable into a bug report.
• List Terminals — QuickPick of every Claws-known terminal (id · name · wrapped/unwrapped · pid); selecting one focuses it.
• Rebuild Native PTY — runs @electron/rebuild against the bundled node-pty. Use after a VS Code major upgrade if pipe-mode fallback kicks in.
• Uninstall Cleanup — scans open workspace folders, inventories every Claws-installed file (.mcp.json entry, .claws-bin/, .claude/commands/claws-*, skill dirs, .vscode/extensions.json recommendation, fenced block in CLAUDE.md), shows a per-folder confirmation, removes only what was installed, and writes a summary to the Output channel.

All seven commands are also reachable from the command palette under the Claws: category.

MCP Server — Native Claude Code Integration (project-local)

As of v0.4, every project you install into gets its own .mcp.json pointing at a vendored mcp_server.js under .claws-bin/. Each project's Claws setup is independent — customize per-project, commit with the repo, or gitignore it. The installer handles this automatically.

// <project>/.mcp.json  (generated at install time — absolute paths, machine-specific)
{
  "mcpServers": {
    "claws": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/.claws-bin/mcp_server.js"],
      "cwd": "/absolute/path/to/project",
      "env": { "CLAWS_SOCKET": "/absolute/path/to/.claws/claws.sock" }
    }
  }
}

The installer pins absolute paths at install time so the server resolves correctly regardless of which directory Claude Code is launched from.

Tools (claws/1 — terminal control): claws_list · claws_create · claws_send · claws_exec · claws_read_log · claws_poll · claws_close · claws_worker

Tools (claws/2 — multi-agent): claws_hello · claws_subscribe · claws_publish · claws_broadcast · claws_ping · claws_peers

Claws/2 — Multi-Agent Orchestration Protocol

As of v0.6, Claws includes a built-in coordination layer so an orchestrator Claude can spawn and manage a fleet of worker Claudes over the same socket — no extra infrastructure required.

• Peer identity — each agent registers with claws_hello (role: orchestrator | worker | observer) and gets a stable peerId for the session
• Pub/sub message bus — claws_subscribe / claws_publish / claws_broadcast with * and ** wildcard topic patterns; server-push frames delivered without polling
• Task registry — orchestrator assigns tasks via claws_task_assign; workers report progress with claws_task_update and claws_task_complete; full lifecycle: pending → running → succeeded / failed / skipped
• Backward compatible — all claws/1 terminal-control commands continue to work unchanged

Quick start: type /claws-v2-orchestrate in an orchestrator Claude session to see the step-by-step bootstrap guide.

AI Worker Orchestration (blocking lifecycle)

claws_worker is a single blocking tool call that runs the full worker lifecycle: spawn a wrapped terminal → launch Claude Code with full permissions → detect boot → send mission → poll the capture buffer for MISSION_COMPLETE (or a custom marker) → harvest the last N lines → auto-close the terminal → return a structured result.

{
  "name": "claws_worker",
  "arguments": {
    "name": "refactor-auth",
    "mission": "Refactor auth.ts to use bcrypt. Write MISSION_COMPLETE when done.",
    "timeout_ms": 900000,
    "harvest_lines": 300
  }
}

Returns { status: "completed" | "failed" | "timeout", terminal_id, duration_ms, marker_line, harvest, cleaned_up }. No manual polling, no manual cleanup. Pass detach: true to keep the old fire-and-forget behavior.

Cross-Device Control (planned)

WebSocket transport with token auth + TLS. SSH tunnel works today:

ssh -L 9999:/remote/.claws/claws.sock user@remote

What Gets Installed

The installer writes files in two scopes: the machine (once) and the project you ran it in (per-project, re-run for each project you want Claws in).

Machine-level (written once, shared by all projects)

Project-level (written into the project you installed from)

Opt-in: global install

Set CLAWS_GLOBAL_CONFIG=1 to mirror the per-project config into ~/.claude/. Set CLAWS_GLOBAL_MCP=1 to also register the MCP globally in ~/.claude/settings.json. Both default to off.

Uninstall

Machine-wide: rm -rf ~/.claws-src, remove the extension symlink, remove the shell-hook line. Project-level: rm -rf .claws-bin .claude/commands/claws-*.md .claude/rules/claws-default-behavior.md .claude/skills/claws-* .mcp.json and delete the fenced block from CLAUDE.md.

Documentation

Powered by Claude Opus

Claws was designed for and tested with Claude Opus — the model with the deepest reasoning for multi-terminal orchestration.

Roadmap

• v0.3 ✅ Zero dependencies — Node.js only
• v0.4 ✅ TypeScript rewrite, Pseudoterminal (no glitching), blocking claws_worker, project-local install, dynamic CLAUDE.md, automatic legacy migration
• v0.5 ✅ Hardening sweep — introspect command, status bar item, Health Check / Uninstall Cleanup, chord keybindings, UUID profile adoption, hot-reloadable config, bundled node-pty, 57 automated checks
• v0.6 ✅ Agentic SDLC Protocol — claws/2 peer registry, pub/sub message bus, task assignment engine (orchestrator→worker), 6 new MCP tools, 33 new automated checks
• v0.7 — WebSocket transport, cross-device control, team config, device discovery, web dashboard, VS Code Marketplace publish

License

MIT · Anish Neunaha · Website