@vibe-orchestrator/executor

Local executor for Vibe Orchestrator. Runs on your dev machine, spawns AI coding agents, and streams results back to the VPS server over WebSocket.

Installation

npm install -g vibe-executor

Or run from source:

cd packages/executor
bun run dev

CLI Commands

vibe-executor setup

Interactive configuration. Prompts for server URL and API key, saves to ~/.vibe-executor/config.json.

vibe-executor setup
# Server URL: https://your-vps.example.com
# API Key: a1b2c3d4...
# Configuration saved.

vibe-executor start

Connect to the orchestrator server and begin accepting agent spawn commands.

vibe-executor start           # foreground mode
vibe-executor start --daemon  # background mode (writes PID file)

On connect, the executor sends its runtime capabilities (which CLIs are installed) to the server.

vibe-executor stop

Stop a running daemon executor.

vibe-executor stop
# Sent SIGTERM to executor (PID 12345).

vibe-executor status

Check configuration and executor running state.

vibe-executor status
# Configuration: found
#   Server URL: https://your-vps.example.com
# Executor: running (PID 12345)

vibe-executor setup-ide

Automatically write MCP configuration files for supported IDEs. Backs up existing configs before modifying.

vibe-executor setup-ide
# Wrote Claude Code config: ~/.claude/.mcp.json
# Wrote Cursor config: ~/.cursor/mcp.json
# Wrote Antigravity config: ~/.antigravity/mcp.json

Runtime Detection

On startup, the executor checks which agent CLIs are available:

| Runtime | CLI Command | Detection | |---------|-------------|-----------| | Claude Code | claude | claude --version | | Gemini CLI | gemini | gemini --version | | Codex CLI | codex | codex --version |

Available runtimes are reported to the server. The server only dispatches tasks to runtimes the executor supports.

How Agents Are Spawned

When the server sends a spawn_agent message, the executor:

1. Validates the working directory exists
2. Spawns the appropriate CLI with task description and system prompt
3. Streams stdout/stderr back to the server as agent_log messages
4. Reports completion or error when the process exits

Agent CLI invocations:

# Claude Code
claude --system-prompt "..." --print "task description"

# Gemini CLI
gemini --yolo -p "task description"

# Codex CLI
codex --approval-mode auto-edit "task description"

MCP server configs can be injected so spawned agents can call back to the orchestrator.

Configuration

Stored at ~/.vibe-executor/config.json:

{
  "serverUrl": "https://your-vps.example.com",
  "apiKey": "your-api-key",
  "registeredProjects": {}
}

Daemon Mode

With --daemon, the executor writes its PID to ~/.vibe-executor/executor.pid and runs in the background. Use vibe-executor stop to send SIGTERM.

Troubleshooting

"No configuration found" -- Run vibe-executor setup first.

"Disconnected ... Reconnecting" -- The WebSocket connection was lost. The executor auto-reconnects with backoff.

Agent spawn fails -- Check that the runtime CLI is installed and in your PATH. Run vibe-executor status to verify.

Working directory does not exist -- The server sends a workingDir with each spawn. Make sure the project's repo_path points to a valid local directory.