克劳德命令运行器

Prerequisites

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

Installation

Quick Install

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

Rebuild with the SAME signing identity you used originally. Without it, build.sh

(build.sh auto-detects a single identity; export to be explicit.)

export CCR_CODESIGN_IDENTITY="<your-cert-sha1>" # persist in ~/.zshrc so you don't forget ./build.sh

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_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:

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: claude-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

Development Setup

git clone https://github.com/yourusername/claude-command-runner.git
cd claude-command-runner
swift package resolve
swift build

Usage

Example Workflows

Simple Command:

You: "Check my Swift version"
Claude: [execute_with_auto_retrieve: swift --version]
Claude: "You're running Swift 6.0.2"

Build Pipeline:

You: "Build, test, and package my app"
Claude: [execute_pipeline with build → test → package steps]
Claude: "Pipeline complete! Build: ✅ Test: ✅ Package: ✅"

Streaming Long Build:

You: "Build this large project"
Claude: [execute_with_streaming: swift build -c release]
Claude: "Building... [live updates every 3 seconds]"
Claude: "Build completed in 45 seconds!"

Using Templates:

You: "Save a template for deploying to staging"
Claude: [save_template: name="deploy-staging", template="cd {{project}} && ./deploy.sh staging"]

You: "Deploy MyApp to staging"
Claude: [run_template: name="deploy-staging", variables={project: "MyApp"}]

Environment Context (v5.0):

You: "What's my current dev environment?"
Claude: [get_environment_context]
Claude: "You're on branch feature/auth, Python venv active, Node 20.11, 3 Docker containers running."

Workspace Profiles (v5.0):

You: "Save this as my API project profile"
Claude: [save_workspace_profile: name="api-project", directory="~/Projects/api", ...]

You: "Switch to the API project"
Claude: [load_workspace_profile: name="api-project"]

File Watching (v5.0):

You: "Rebuild whenever a Swift file changes"
Claude: [add_file_watch: path="./Sources", pattern="*.swift", command="swift build"]
Claude: "Watching ./Sources for *.swift changes. Will run swift build on each change."

SSH Remote Execution (v5.0):

You: "Check disk space on the staging server"
Claude: [ssh_execute: host="staging.example.com", username="deploy", command="df -h"]
Claude: "Here's the disk usage on staging..."

Then in your shell rc (~/.zshrc, ~/.config/fish/config.fish, etc.):

export CCR_CODESIGN_IDENTITY="<the-sha1-hash-from-above>"

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

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

**Verify:**

#### 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:

Verify the signature survived the copy:

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

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

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 rebuilds with different cdhashes. Wipe them for the bundle:

Each line should print "Successfully reset". If you see "no entries", that's also fine — means TCC had nothing recorded yet.

Step 6 — Grant the three TCC permissions (Full Disk Access is the surprise one)

In System Settings → Privacy & Security, add /Applications/Claude Command Runner.app to each of:

1. Full Disk Access — unexpected but mandatory. macOS sandbox does a preflight check for kTCCServiceSystemPolicyAllFiles before allowing osascript to spawn for keystroke chains. Without FDA on the bundle, the sandbox denies before TCC's AppleEvents check ever fires, and you get the misleading "send keystrokes" error.
2. Input Monitoring — for kTCCServiceListenEvent / kTCCServicePostEvent (synthetic keystroke generation).
3. Accessibility — for the keystroke AppleEvent action itself.

Each grant requires Touch ID / admin password to confirm. Bundle name appears as "Claude Command Runner" in the panels.

Step 7 — Restart Claude Desktop, trigger once, grant the Automation prompt

⌘Q Claude Desktop, reopen. On your first execute_command, macOS may show one more prompt — Automation → "Claude Command Runner wants to control System Events" — click Allow. After that, it's permanent. Future rebuilds don't reset anything (the cert keeps cdhash stable; the bundle keeps the identity stable).

---

Configuration

The configuration file is located at ~/.claude-command-runner/config.json:

{
  "terminal": {
    "preferred": "auto",
    "fallbackOrder": ["Warp", "WarpPreview", "iTerm", "Terminal"]
  },
  "security": {
    "blockedCommands": ["rm -rf /", "format"],
    "maxCommandLength": 1000
  },
  "history": {
    "enabled": true,
    "maxEntries": 10000
  },
  "notifications": {
    "enabled": true,
    "soundEnabled": true,
    "showOnSuccess": false,
    "showOnFailure": true,
    "minimumDuration": 10
  },
  "fileWatching": {
    "maxWatchers": 5,
    "defaultDebounce": 2.0,
    "autoExpireMinutes": 60
  },
  "ssh": {
    "defaultTimeout": 30,
    "allowPasswordAuth": false
  },
  "interactiveDetection": {
    "enabled": true,
    "customPatterns": []
  }
}

Templates are stored separately at ~/.claude-command-runner/templates.json. Workspace profiles are stored at ~/.claude-command-runner/profiles.json. SSH profiles are stored at ~/.claude-command-runner/ssh_profiles.json.

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

Q: What happens if a pipeline step fails?

A: Depends on the on_fail setting: - stop – Pipeline halts immediately, remaining steps are skipped - continue – Error is logged, pipeline continues to next step - warn – Warning is shown, pipeline continues

Q: Can I nest pipelines or run templates inside pipelines?

A: Not directly. You can create templates that contain multiple commands separated by && or ;, or compose by calling run_template and execute_pipeline from the same conversation.

Pipeline Steps Skipped Unexpectedly

1. Check the on_fail setting – stop will skip remaining steps
2. Verify each command works individually first
3. Check exit codes in the pipeline summary

Q: When should I use pipelines vs regular commands?

A: Use pipelines when you need: - Multiple sequential commands - Conditional logic (stop on build failure, continue on test failure) - A summary of all steps with timing - CI/CD-style workflows

🤔 Frequently Asked Questions

🛠️ Troubleshooting