# Warp Command Runner

> Give any chat AI a real terminal. Local stdio MCP for Warp, Claude Desktop, and other hosts. macOS, Swift.

- **Type:** MCP server
- **Install:** `agentstack add mcp-m-pineapple-warp-command-runner`
- **Verified:** Pending review
- **Seller:** [M-Pineapple](https://agentstack.voostack.com/s/m-pineapple)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [M-Pineapple](https://github.com/M-Pineapple)
- **Source:** https://github.com/M-Pineapple/warp-command-runner

## Install

```sh
agentstack add mcp-m-pineapple-warp-command-runner
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://app.warp.dev/referral/G9W3EY) 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](https://app.warp.dev/referral/G9W3EY). 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](https://app.warp.dev/referral/G9W3EY)** (Grok, Claude, GPT, Gemini — whatever Warp is set to) | `~/.warp/.mcp.json` | Yes — best fit. See [docs/WARP_AGENT.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:

```json
{
  "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:

```json
{
  "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:

```json
// 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](https://app.warp.dev/referral/G9W3EY) 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](https://app.warp.dev/referral/G9W3EY). 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](https://app.warp.dev/referral/G9W3EY) strongly recommended)

### Quick Install

1. Clone and build:
```bash
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`.

2. **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/WARP_AGENT.md`](docs/WARP_AGENT.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.

3. **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.

4. **Restart your MCP host(s)** (Warp, Claude Desktop, ChatGPT desktop, …).

5. **(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:

```bash
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:
```bash
# 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)

```bash
./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:**
```bash
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:

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

Verify the signature survived the copy:
```bash
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`):
```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](https://github.com/M-Pineapple)
- **Source:** [M-Pineapple/warp-command-runner](https://github.com/M-Pineapple/warp-command-runner)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-m-pineapple-warp-command-runner
- Seller: https://agentstack.voostack.com/s/m-pineapple
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.