Claude Command Runner

🚀 Claude Command Runner

A powerful Model Context Protocol (MCP) server that bridges Claude Desktop and terminal applications, enabling seamless command execution with intelligent output retrieval and comprehensive v3.0 features.

🚀 Quick Start

Claude Command Runner revolutionizes the development workflow by allowing Claude to execute terminal commands directly from conversations, automatically capture output with intelligent timing, track command history and patterns, and maintain security with configurable policies.

✨ Features

🆕 What's New in v3.0

• Enhanced Auto-Retrieve: Progressive delays with smart command detection
• Rock-Solid Stability: Fixed server crashes, runs persistently
• Database Integration: SQLite command history and analytics
• Configuration System: Customizable security and behavior settings
• Build Intelligence: Automatically waits longer for compilation commands

🎯 Key Features

Smart Auto-Retrieve

The execute_with_auto_retrieve command now 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

Complete Feature Set

• ✅ Two-way communication with automatic output capture
• ✅ Progressive delay system for all command types
• ✅ SQLite database for command history
• ✅ Configurable security policies
• ✅ Multi-terminal support (Warp recommended)
• ✅ Command suggestions based on history

📊 Why Warp Terminal?

For the best experience, we recommend Warp Terminal:

💡 Usage Tip

Download Warp Terminal - It's free and makes Claude Command Runner significantly more powerful!

📦 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
./build.sh

2. Configure Claude Desktop by adding to your MCP settings:

{
  "claude-command-runner": {
    "command": "/path/to/claude-command-runner/.build/release/claude-command-runner",
    "args": ["--port", "9876"],
    "env": {}
  }
}

3. Restart Claude Desktop

💻 Usage Examples

Basic Usage

Available Tools:

1. execute_command - Execute with manual output retrieval
2. execute_with_auto_retrieve - Execute with intelligent auto-retrieval ⭐
3. get_command_output - Manually retrieve command output
4. preview_command - Preview without executing
5. suggest_command - Get command suggestions

Advanced Usage

Example Workflow:

You: "Build my Swift project"
Claude: [Executes: swift build]
[Waits intelligently up to 77 seconds]
Claude: "Build completed successfully! Here's the output..."

📚 Documentation

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
  }
}

Frequently Asked Questions

Q: Why does the server crash sometimes?

A: This was a major issue in earlier versions. v3.0 completely fixes server stability by removing problematic background tasks and implementing a safer progressive delay system.

Q: How long will auto-retrieve wait for my command?

A: It depends on the command type:

• Simple commands: 6 seconds
• Git/npm commands: 20 seconds
• Build commands: 77 seconds
• Unknown commands: 30 seconds

Q: Can I use this with Terminal.app or iTerm2?

A: Yes, basic command execution works with any terminal. However, automatic output capture and advanced features require Warp Terminal. Get Warp free here.

Q: Is it secure to let Claude run commands?

A: Yes! Every command requires manual approval (pressing Enter), and you can configure blocked commands and patterns in the config file. Claude cannot execute anything without your explicit consent.

Q: What happens if my build takes longer than 77 seconds?

A: The auto-retrieve will timeout and provide the command ID. You can then use get_command_output with that ID to retrieve the results when ready.

Q: Where is my command history stored?

A: In an SQLite database at ~/.claude-command-runner/claude_commands.db. It tracks all commands, outputs, exit codes, and execution times.

Q: Can I contribute to this project?

A: Absolutely! Fork the repo, make your changes, and submit a PR. Check out our contributing guidelines below.

Q: Why do you recommend Warp so strongly?

A: Warp provides APIs that enable features impossible with other terminals:

• Automatic output capture without polling
• Integrated command history
• Modern async architecture

Troubleshooting

MCP Not Responding

1. Check if the server is running: lsof -i :9876
2. Restart Claude Desktop
3. Rebuild with ./build.sh

Commands Not Appearing in Terminal

1. Ensure Warp/WarpPreview is running
2. Check Claude Desktop logs for errors
3. Verify your MCP configuration path

Auto-Retrieve Not Working

1. Ensure you're using execute_with_auto_retrieve (not execute_command)
2. Check if command output file exists: ls /tmp/claude_output_*.json
3. For long commands, wait for timeout message then use manual retrieval

Database Not Logging Commands

If commands execute but aren't saved to the database:

1. Check database integrity:

   sqlite3 ~/.claude-command-runner/claude_commands.db "PRAGMA integrity_check;"
   

2. If you see errors or "missing from index" messages, the database is corrupted:

   # Backup and remove corrupted database
   mv ~/.claude-command-runner/claude_commands.db ~/.claude-command-runner/claude_commands.db.backup
   # Restart Claude Desktop - a new database will be created automatically
   

3. Verify database is working:

   # Check if commands are being logged
   sqlite3 ~/.claude-command-runner/claude_commands.db "SELECT COUNT(*) FROM commands;"
   

4. Check for multiple server instances:

   ps aux | grep claude-command-runner | grep -v grep
   # If you see multiple instances, kill all and restart Claude Desktop
   

The v3.0 release includes automatic corruption detection and recovery, but if issues persist, manually removing the database file will force a clean recreation.

Architecture

┌─────────────────┐         ┌──────────────────┐         ┌────────────────┐
│ Claude Desktop  │ ←────→  │ Command Runner   │ ←────→  │ Warp Terminal  │
│                 │  MCP    │ MCP Server       │ Script  │                │
│ • Send commands │         │ • Port 9876      │         │ • Execute      │
│ • Auto-retrieve │         │ • Progress Delay │         │ • Capture      │
│ • Get output    │         │ • SQLite DB      │         │ • Return       │
└─────────────────┘         └──────────────────┘         └────────────────┘

Contributing

We love contributions! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

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

Support This Project

If Claude Command Runner has helped enhance your development workflow or saved you time with intelligent command execution, consider supporting its development:

Your support helps me:

• Maintain and improve Claude Command Runner with new features
• Keep the project open-source and free for everyone
• Dedicate more time to addressing user requests and bug fixes
• Explore new terminal integrations and command intelligence

Thank you for considering supporting my work! 🙏

📄 License

MIT License - see LICENSE file for details

Built with ❤️ by 🍍

If you find this project helpful, give it a ⭐ and try Warp Terminal!