Claude Command Runner

Claude Command Runner

Lets Claude actually use your terminal. You ask, Claude types the command into your Warp tab, captures the output, and tells you what happened. It's a Model Context Protocol (MCP) server with 40 tools — command execution, project setups, file watching, SSH, clipboard, environment intelligence — and the same binary works from both Claude Desktop and Warp's built-in AI agent panel. macOS, Swift, open source.

> Built for Warp Terminal (free, open source AGPL-3.0). The 5 most powerful tools route commands visibly into your active Warp tab — that's the magic of this MCP. If you don't use Warp yet, grab it here — it pairs with this MCP for what's probably the closest thing to "Claude with a real terminal" you can get right now.

🚀 What's New in v6.0.0 — Warp re-pivot

Triggered by Warp going open source under AGPL-3.0 (github.com/warpdotdev/warp) in May 2026. v6.0 re-establishes Warp as the primary integration target and adds a new install path: Warp's native agent panel.

• Dual-consumer architecture: register claude-command-runner in ~/.warp/.mcp.json and Warp's built-in agent (which uses your configured LLM — Claude Sonnet, Opus, etc.) calls the same tools Claude Desktop calls. Same binary, same code, two consumers. See [docs/WARP_AGENT.md](docs/WARP_AGENT.md).
• Deeplinks replace AppleScript for tab/window operations: open_terminal_tab now uses warp://action/new_tab?path=.... No menu-clicking, no Accessibility permission for the open path.
• OSC 777 emitter (emit_warp_event): build printf invocations that surface structured events into Warp's notification UI. Schema reimplemented from upstream event/v1.rs (no vendoring).
• Workspace profiles → Warp launch configs: save_workspace_profile accepts include_warp_launch_config: true to also write a YAML to ~/.warp/launch_configurations/, making the profile appear in Warp's launch UI.
• Optional shell shim (Tier E, opt-in): helper/install-shim.sh adds zsh/bash hooks that emit preexec/command_finished events to a per-uid Unix socket the MCP listens on. Auto-disables outside Warp panes. Observability surface in v6.0; auto-routing execute_command through it is deferred to v6.0.x.
• Cleanup: ~460 LOC of dead code removed (obsolete Warp DB integration, orphan TCP listener, unreachable background monitor). Tool count corrected: README claimed 30, reality was 36, v6.0 ships 39.
• Reproducible build: swift-sdk pinned to 0.10.x with a deterministic scripts/patch-swift-sdk.sh so a fresh clone builds without manual patches.

> Honest caveat: the "Claude" replying in Warp's agent panel is Warp's agent (running whichever LLM you configure in Warp's AI settings), not your Claude Desktop instance. Both can call the MCP; they don't share conversations. v6.0 does not bridge them.

What's New in v5.0.0 (history)

v5.0.0: 36 tools, up from 12.

• Clipboard Bridge: Read from and write to the macOS clipboard without leaving the conversation
• macOS Notifications: Get native notifications when long-running commands finish
• Environment Intelligence: Probe your terminal context (git branch, active venv, Node version, Docker containers) in one call
• Output Parsers: Structured JSON parsing for git status, docker ps, test results, and more
• Environment Snapshots: Capture and diff environment variables before/after installs or config changes
• Workspace Profiles: Save and restore project contexts (directory, env vars, common commands) per project
• Multi-Terminal Sessions: Open, name, and send commands to multiple terminal tabs
• Interactive Command Detection: Smart detection of interactive commands (vim, ssh, python REPL) with graceful handling
• File System Watchers: Watch directories for changes and trigger commands automatically
• SSH Remote Execution: Run commands on remote hosts via SSH key authentication

Previous Releases (Included)

• v4.0: Command pipelines, output streaming, reusable templates
• v3.0: Smart auto-retrieve, SQLite history, configurable security

Overview

Claude Command Runner is a dual-consumer MCP server — the same binary serves Claude Desktop and Warp's native agent panel. It enables an LLM (whichever you've configured in either client) to:

• Execute terminal commands directly from conversations
• Chain commands with conditional logic using pipelines
• Stream output in real-time for long builds
• Save and reuse command templates with variables
• Automatically capture output with intelligent timing
• Track command history and patterns
• Read/write the macOS clipboard
• Probe environment context (git, venv, Docker, Node)
• Parse command output into structured JSON
• Manage workspace profiles per project (with optional emission as Warp launch configs)
• Open terminal tabs (via warp:// deeplinks; AppleScript fallback for non-Warp terminals) and send commands to the active tab
• Watch files and trigger commands on changes
• Execute commands on remote hosts via SSH
• (v6.0) Surface tool-execution status to Warp's UI as OSC 777 warp://cli-agent events
• (v6.0, opt-in) Stream clean preexec / command-finished events from your shell to the MCP via a per-uid Unix domain socket

🧭 Which Claude product does this work with?

claude-command-runner is an MCP server, so any Anthropic surface that consumes MCP servers can call its 40 tools — but the value-add varies sharply by consumer, and you should pick deliberately.

| Consumer | Where to register | Value-add | Recommended? | |---|---|---|---| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | High. execute_command types into your Warp tab so terminal action is visible alongside the chat. Chat stays focused on reasoning; the terminal becomes the work surface. | ✅ Primary use case | | Cowork (inside Claude Desktop) | Same config as Claude Desktop | High. Same model — your collaborators see the chat; commands run in your Warp pane. | ✅ Yes | | Warp's native agent panel | ~/.warp/.mcp.json (see [docs/WARPAGENT.md](docs/WARPAGENT.md)) | High. Type into Warp's agent panel, agent calls our tools, output renders inline in Warp's chat. Same MCP, same code, second consumer. | ✅ Yes — see WARP_AGENT.md | | Claude Code (CLI) | ~/.claude.json | **Marginal — only if you want commands in a different Warp tab from the one Claude Code is in.** Claude Code already runs inside a terminal pane (Warp or otherwise) and has its own built-in Bash tool that spawns subprocesses with pipes. For routine command execution Claude Code's built-in is shorter, faster, and doesn't need TCC permissions. The MCP is only worth registering if you want commands to land visibly in a separate Warp tab you control — e.g. as a "scratch" pane you can scroll through later. | ⚠️ Optional, niche | | Other terminals (iTerm2, Terminal.app, Alacritty) | Any of the above | Low. Most of v6.0's value is Warp-specific: warp:// deeplinks, OSC 777 events, Warp agent integration, launch configs. The 24 server-side tools (clipboard, SSH, env snapshots, file watcher, etc.) work everywhere — but at that point you're using maybe two-thirds of the surface area. | ❌ Look elsewhere |

Quick decision tree

• You use Warp + Claude Desktop and want commands visible in your terminal? → Register here. Primary use case.
• You use Warp + Claude Code and want everything in one pane? → Don't bother. Claude Code's built-in Bash tool is enough.
• **You use Warp + Claude Code and want commands in a separate observable Warp tab?** → Register and use execute_command deliberately.
• You use Warp's native agent panel? → Register in ~/.warp/.mcp.json.
• You don't use Warp? → This isn't the right MCP for you. Look at simpler subprocess-based MCPs.

The "40 tools" headline is honest but slightly misleading: 5 of those tools (the AppleScript-keystroke ones — execute_command, execute_with_auto_retrieve, execute_with_streaming, run_template, send_to_session) are the Warp-routing crown jewels, and 25 of them are pure server-side utilities that any subprocess-based MCP could provide. The remaining 10 sit in between (deeplinks, OSC 777, profiles, file watchers). If the Warp-routing 5 don't appeal, the rest of this MCP is fine but unremarkable.

🎯 Key Features

Command Pipelines

Chain multiple commands with intelligent failure handling:

{
  "steps": [
    {"name": "Build", "command": "swift build", "on_fail": "stop"},
    {"name": "Test", "command": "swift test", "on_fail": "continue"},
    {"name": "Package", "command": "swift build -c release", "on_fail": "stop"}
  ]
}

Failure modes:

• stop – Halt pipeline on failure
• continue – Log error and proceed to next step
• warn – Show warning and continue

Output Streaming

Real-time output for long-running commands:

{
  "command": "swift build -c release",
  "update_interval": 3,
  "max_duration": 180
}

Perfect for:

• Long compilation processes
• Test suites
• Any command that previously "hung" waiting for output

Command Templates

Save reusable patterns with variable substitution:

// Save a template
{
  "name": "swift-release",
  "template": "cd {{project}} && swift build -c release",
  "category": "Swift Development",
  "description": "Build Swift project in release mode"
}

// Run with variables
{
  "name": "swift-release",
  "variables": {"project": "~/GitHub/MyApp"}
}

Templates are stored in ~/.claude-command-runner/templates.json and persist across sessions.

Smart Auto-Retrieve

The execute_with_auto_retrieve command intelligently detects command types and adjusts wait times:

• Quick commands (echo, pwd): 2-6 seconds
• Moderate commands (git, npm): up to 20 seconds
• Build commands (swift build, make): up to 77 seconds
• Test commands: up to 40 seconds

📊 Why Warp Terminal?

Warp Terminal is the primary integration target. The other terminals work for the basics — what Warp uniquely unlocks in v6.0 is documented integration surfaces:

| Feature | Warp | Terminal.app | iTerm2 | |---------|------|--------------|---------| | warp:// deeplinks for tab/window | ✅ (v6.0 uses these) | ❌ | ❌ | | Native MCP agent panel — chat with Claude in the terminal | ✅ (~/.warp/.mcp.json) | ❌ | ❌ | | OSC 777 cli-agent event channel for status surfacing | ✅ | ❌ | ❌ | | Workspace profile → recognized launch config | ✅ (~/.warp/launch_configurations/) | ❌ | ❌ | | AppleScript-driven new tab + keystroke send | ✅ | ✅ | ✅ | | Modern UI/UX | ✅ | ⚠️ | ⚠️ |

Output capture (/tmp/.json polling) and the 24 tools that don't touch the terminal at all (clipboard, SSH, file watch, env snapshots, etc.) work identically across all terminals.

> 💡 Get Warp: Download Warp Terminal – it's free, open source (AGPL-3.0), and makes the v6.0-specific surfaces above available to you.

Installation

Prerequisites

• macOS 13.0 or later
• Swift 6.0+ (Xcode 16+)
• Claude Desktop
• A supported terminal (Warp strongly recommended)

Quick Install

1. Clone and build:

git clone https://github.com/M-Pineapple/claude-command-runner.git
cd claude-command-runner

# For the 5 keystroke-routing tools (execute_command, etc.) to work, the build
# must be SIGNED with your code-signing identity. build.sh auto-detects a single
# Apple Development / Developer ID identity; to be explicit (or if you have
# several), export it first — find yours with:
#   security find-identity -v -p codesigning
export CCR_CODESIGN_IDENTITY=""   # optional if auto-detect finds one; persist in ~/.zshrc
./build.sh

> Only need the 34 non-keystroke tools (incl. execute_pipeline)? An unsigned build is fine — skip the export.

1. Pick your consumer(s) — you can install for one or both. v6.0.3 ships a .app bundle wrapper — point at the binary INSIDE the bundle (the wrapper carries the Info.plist that macOS Sequoia+ needs to prompt for TCC permissions; without it, the 5 keystroke-routing tools silently fail):

A — Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json): ``json { "mcpServers": { "claude-command-runner": { "command": "/path/to/claude-command-runner/.build/release/claude-command-runner.app/Contents/MacOS/claude-command-runner", "args": [] } } } ``

B — Warp's native agent (~/.warp/.mcp.json): ``json { "mcpServers": { "claude-command-runner": { "command": "/path/to/claude-command-runner/.build/release/claude-command-runner.app/Contents/MacOS/claude-command-runner", "args": [] } } } ` See [docs/WARPAGENT.md`](docs/WARPAGENT.md) for the full guide.

> Upgrading from v6.0.0–6.0.2? Edit your existing config file and append .app/Contents/MacOS/claude-command-runner to the path. The legacy bare-binary path still works for the 34 non-keystroke tools, but execute_command / execute_with_auto_retrieve / execute_with_streaming / run_template / send_to_session will silently fail without the bundle path.

1. Grant Accessibility permission (only required for send_to_session keystroke injection in v6.0; tab/window opening uses deeplinks and does not require it):

• Open System Settings → Privacy & Security → Accessibility
• Click + and navigate to claude-command-runner/.build/release/
• Press Cmd+Shift+. to reveal the hidden .build folder
• Select the claude-command-runner binary and toggle it on

> Important: macOS tracks permissions by binary identity. After every rebuild (./build.sh), you must remove the old entry and re-add the new binary in Accessibility settings.

1. Restart your client(s) (Claude Desktop and/or Warp).

1. (Optional) Install the shell shim for cleaner block-boundary capture:

``bash helper/install-shim.sh ` See helper/shell-shim.zsh / helper/shell-shim.bash for the implementation. Uninstall with helper/uninstall-shim.sh`.

Upgrading from a previous version

If you already have a signed install working (TCC permissions granted), upgrading is:

cd claude-command-runner
git pull

# Rebuild with the SAME signing identity you used originally. Without it, build.sh
# falls back to an ad-hoc-signed bundle, macOS sees a new identity, and your
# keystroke (TCC) grants stop applying → error 1002 on execute_command.
# (build.sh auto-detects a single identity; export to be explicit.)
export CCR_CODESIGN_IDENTITY=""   # persist in ~/.zshrc so you don't forget
./build.sh

# Confirm it signed with your cert (NOT adhoc) BEFORE replacing your good bundle:
codesign -dvv .build/release/claude-command-runner.app 2>&1 | grep -E "Authority=Apple|Signature=adhoc"

# Replace the deployed bundle (rm first — cp -R onto an existing .app nests it):
rm -rf "/Applications/Claude Command Runner.app"
cp -R .build/release/claude-command-runner.app "/Applications/Claude Command Runner.app"

Then restart Claude Desktop. Because the bundle keeps the same identifier and is signed with the same certificate, your existing TCC grants (Automation, Input Monitoring, Accessibility, Full Disk Access) carry over — no re-granting needed. If the keystroke tools start failing with error 1002 after an upgrade, you almost certainly rebuilt unsigned; re-sign with your cert and redeploy.

🛡️ macOS Sequoia full setup recipe (the 7 ordered steps)

> If execute_command / execute_with_auto_retrieve / execute_with_streaming / run_template / `send

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: M-Pineapple
• Source: M-Pineapple/claude-command-runner
• License: MIT

Install and usage instructions live in the source repository linked above.