Warp Command Runner

Warp Command Runner

Give any chat AI a real terminal. You ask in Warp, Claude Desktop, ChatGPT desktop, or any other MCP host. The model types the command into your Warp tab, captures the output, and tells you what happened. Forty tools: command execution, project setups, file watching, SSH, clipboard, environment intelligence. macOS, Swift, open source.

This is for people who don't live in Cursor or Claude Code. If you already chat with Grok, ChatGPT, Claude, or Gemini from a desktop app (especially Warp's agent panel), add this MCP and that chat can read your files and run commands on your machine.

> Built for Warp Terminal. The five most powerful tools route commands visibly into your active Warp tab. Register the same binary with as many MCP hosts as you want — the server speaks standard MCP over stdio and does not care which model is calling.

Can any cloud AI use this? Any local MCP host can. A website (grok.com, chatgpt.com, claude.ai in the browser) cannot spawn a process on your Mac. Full matrix: [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).

What's new in v7.0.0 — rebrand

Formerly Claude Command Runner. Same engine, host-agnostic name:

• Product, binary, bundle ID, and config dir renamed to Warp Command Runner (warp-command-runner, ~/.warp-command-runner)
• Existing ~/.claude-command-runner data is copied on first launch (the old folder is left in place)
• MCP serverInfo name is Warp Command Runner so every host lists it that way
• Config snippets for Warp, Claude Desktop, ChatGPT desktop, Cursor, VS Code, and a generic stdio host
• Honest compatibility doc: stdio MCP works everywhere a local host exists; it is not a remote/HTTPS MCP for browser chats

v6.x history (Warp deeplinks, OSC 777, dual-consumer Warp Agent, 40 tools) is unchanged — see [CHANGELOG.md](CHANGELOG.md).

Overview

Warp Command Runner is an MCP server. One binary, any MCP client:

• Execute terminal commands from a conversation
• Chain commands with pipelines and failure modes
• Stream output for long builds
• Save and reuse command templates with variables
• Auto-capture output with intelligent timing
• Track command history
• Read/write the macOS clipboard
• Probe environment context (git, venv, Docker, Node)
• Parse command output into structured JSON
• Manage workspace profiles (optionally as Warp launch configs)
• Open Warp tabs via warp:// deeplinks and send commands to the active tab
• Watch files and trigger commands on changes
• Execute commands on remote hosts via SSH
• Surface status into Warp as OSC 777 warp://cli-agent events
• Optional shell shim: preexec / command-finished events over a Unix socket

🧭 Which app should I register this with?

The protocol is MCP. The value depends on whether the host is local and whether Warp is your terminal. Details in [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).

| Host | Config | Recommended? | |---|---|---| | Warp Agent (Grok, Claude, GPT, Gemini — whatever Warp is set to) | ~/.warp/.mcp.json | Yes — best fit. See [docs/WARPAGENT.md](docs/WARP_AGENT.md) | | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | Yes | | ChatGPT desktop (Connectors / Developer Mode) | host MCP settings; snippet in config/chatgpt-mcp.json | Yes, if your plan exposes local MCP | | VS Code / Continue / Cline / Windsurf | their MCP settings; see config/ | Optional | | Cursor | ~/.cursor/mcp.json | Optional — Cursor already has a terminal | | Claude Code | ~/.claude.json | Niche — it already has Bash | | Browser chats (chatgpt.com, grok.com, claude.ai, Gemini web) | — | No. They cannot launch a local stdio server |

Quick decision tree

• You use Warp and chat with Grok / ChatGPT / Claude / Gemini inside Warp? → Register in ~/.warp/.mcp.json. That's the whole product.
• You use Claude Desktop (or ChatGPT desktop) and want commands visible in Warp? → Register there too. Same binary.
• You use Cursor or Claude Code and want everything in one pane? → You probably don't need this.
• You only use a website chatbot? → This MCP cannot reach that tab. Use a desktop MCP host.

Five of the 40 tools (execute_command, execute_with_auto_retrieve, execute_with_streaming, run_template, send_to_session) are the Warp-routing ones. The rest are ordinary server-side utilities (clipboard, SSH, snapshots, …) that work from any host.

🎯 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 ~/.warp-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. Other terminals work for the basics — Warp uniquely unlocks deeplinks, OSC 777, the native agent panel, and launch configs:

| Feature | Warp | Terminal.app | iTerm2 | |---------|------|--------------|---------| | warp:// deeplinks for tab/window | ✅ | ❌ | ❌ | | Native MCP agent panel — chat with Grok, ChatGPT, Claude, Gemini 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 tools that don't touch the terminal (clipboard, SSH, file watch, env snapshots, etc.) work identically across all terminals.

> Download Warp from warp.dev. It is free, and the Warp-specific surfaces above need it.

Installation

Prerequisites

• macOS 13.0 or later
• Swift 6.0+ (Xcode 16+)
• At least one local MCP host (Warp Agent, Claude Desktop, ChatGPT desktop, VS Code, …) — not a browser chat tab
• A supported terminal (Warp strongly recommended)

Quick Install

1. Clone and build:

git clone https://github.com/M-Pineapple/warp-command-runner.git
cd warp-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 WCR_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 MCP host(s) — you can register the same binary in several. Point at the binary inside the .app bundle (macOS Sequoia+ needs the Info.plist for TCC prompts on the 5 keystroke-routing tools):

A — Warp Agent (~/.warp/.mcp.json) — Grok, ChatGPT, Claude, Gemini, whichever Warp is set to: ``json { "mcpServers": { "warp-command-runner": { "command": "/Applications/Warp Command Runner.app/Contents/MacOS/warp-command-runner", "args": [] } } } ` See [docs/WARPAGENT.md`](docs/WARPAGENT.md).

B — Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) — same JSON shape. ChatGPT desktop, Cursor, VS Code, Continue: copy a snippet from [config/](config/README.md) or [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).

After ./build.sh you can also point at $(pwd)/.build/release/warp-command-runner.app/Contents/MacOS/warp-command-runner before copying the bundle to /Applications/.

> Upgrading from v6.0.0–6.0.2? Edit your existing config file and append .app/Contents/MacOS/warp-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 warp-command-runner/.build/release/
• Press Cmd+Shift+. to reveal the hidden .build folder
• Select the warp-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 MCP host(s) (Warp, Claude Desktop, ChatGPT desktop, …).

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 warp-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 WCR_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/warp-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/Warp Command Runner.app"
cp -R .build/release/warp-command-runner.app "/Applications/Warp Command Runner.app"

Then restart your MCP host. If you upgraded from v6 and kept the same signing certificate, existing TCC grants on com.m-pineapple.claude-command-runner do not transfer to com.m-pineapple.warp-command-runner — re-grant Accessibility / Input Monitoring / Full Disk Access / Automation for the new bundle once. After that, same-cert rebuilds keep the grants.

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

> If execute_command / execute_with_auto_retrieve / execute_with_streaming / run_template / send_to_session fail with osascript is not allowed to send keystrokes (1002) even though you've toggled every panel in System Settings, follow this in order — skipping any step leaves a silent denial somewhere in the chain. The other 34 tools work without any of this; execute_pipeline is a fully-functional substitute if you want to skip the whole TCC saga entirely. > > This is the empirically-verified recipe from a real 6-hour debugging session. v6.0.3+ ships the bundle infrastructure that makes this possible; v6.0.4 is this documentation pass.

The denial pattern. macOS Sequoia's TCC and sandbox have layered, non-obvious requirements for CLI binaries that drive osascript → System Events → keystroke. The error message is misleading — the actual block usually isn't keystroke permission; it's an earlier preflight check that silently aborts the chain. The five gates, in the order macOS evaluates them:

| Gate | TCC service | What grants it | |---|---|---| | 1. Bundle promptability | (n/a — policy) | Bundle in /Applications/, not .build/release/ | | 2. Bundle identity stable | (n/a — codesign) | Signed with a stable cert (cdhash doesn't drift across rebuilds) | | 3. Sandbox FDA preflight | kTCCServiceSystemPolicyAllFiles | Full Disk Access grant on the bundle | | 4. AppleEvents | kTCCServiceAppleEvents | Automation → System Events ☑ | | 5. Keystroke synthesis | kTCCServiceListenEvent / kTCCServicePostEvent | Input Monitoring + Accessibility |

Step 1 — Have an Apple Development cert (or self-signed Code Signing cert)

If you have a paid Apple Developer account, you already have one (check via security find-identity -v -p codesigning). If not, create a self-signed one:

1. Keychain Access → menu Certificate Assistant → Create a Certificate…
2. Name: warp-command-runner, Identity Type: Self Signed Root, Certificate Type: Code Signing
3. Click Create → Continue through warnings → Done

Export the cert identifier for build.sh to find:

# Get the SHA-1 hash (more reliable than the cert name)
security find-identity -v -p codesigning
# Then in your shell rc (~/.zshrc, ~/.config/fish/config.fish, etc.):
export WCR_CODESIGN_IDENTITY=""

Step 2 — Build (creates the signed .app bundle)

./build.sh

build.sh invokes scripts/make-app-bundle.sh, which wraps the CLI in .build/release/warp-command-runner.app/ with a proper Info.plist (CFBundleIdentifier com.m-pineapple.warp-command-runner, the three required NSXxxUsageDescription strings, LSUIElement=true). If WCR_CODESIGN_IDENTITY is set, the bundle is signed with that cert as a unit — stable cdhash across rebuilds.

Verify:

codesign --display --verbose=4 .build/release/warp-command-runner.app | grep -E 'Identifier|TeamIdentifier|CDHash'
codesign --verify --deep --strict .build/release/warp-command-runner.app  # should succeed silently

Step 3 — Install the bundle into /Applications/ (CRITICAL)

macOS refuses to prompt for TCC permissions on bundles in .build/release/ or other dev directories. The bundle must live in /Applications/. Copy it:

cp -R .build/release/warp-command-runner.app "/Applications/Warp Command Runner.app"

Verify the signature survived the copy:

codesign --verify --deep --strict "/Applications/Warp Command Runner.app"

Step 4 — Point your MCP config at the /Applications/ path

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "warp-command-runner": {
      "command": "/Applications/Warp Command Runner.app/Contents/MacOS/warp-command-runner",
      "args": []
    }
  }
}

Mirror in ~/.warp/.mcp.json if you use the Warp Agent path.

Step 5 — Reset stale TCC entries for the bundle ID

If you've been struggling with TCC denials previously, your TCC.db likely has stale Denied entries from earlier reb

…

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/warp-command-runner
• License: MIT

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