Trending-skills opensquirrel-agent-control-plane

---
name: opensquirrel-agent-control-plane
description: Native Rust/GPUI control plane for running multiple AI coding agents (Claude Code, Codex, Cursor, OpenCode) side by side with coordinator/worker delegation, SSH targeting, and persistent sessions.
triggers:
  - run multiple AI agents side by side
  - opensquirrel setup and configuration
  - multi-agent grid with claude and codex
  - coordinate AI coding agents with opensquirrel
  - run claude code and codex simultaneously
  - SSH remote machine targeting for agents
  - persistent agent sessions with opensquirrel
  - delegate tasks between AI coding agents
---

# OpenSquirrel Agent Control Plane

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

OpenSquirrel is a native macOS application (Rust + GPUI, Metal-rendered, no Electron) that acts as a control plane for running Claude Code, Codex, Cursor, and OpenCode simultaneously. It supports automatic sub-agent delegation, remote SSH targeting, MCP server integration, and persistent multi-turn sessions.

## Installation & Build

**Prerequisites:** Rust toolchain, macOS with Metal GPU support.

```bash
git clone https://github.com/Infatoshi/OpenSquirrel
cd OpenSquirrel
cargo build --release
./target/release/opensquirrel

As a macOS .app bundle:

cargo build --release
mkdir -p dist/OpenSquirrel.app/Contents/{MacOS,Resources}
cp target/release/opensquirrel dist/OpenSquirrel.app/Contents/MacOS/OpenSquirrel
cp assets/OpenSquirrel.icns dist/OpenSquirrel.app/Contents/Resources/
open dist/OpenSquirrel.app

Note: The

.app

bundle does not inherit your shell PATH. If

claude

,

npx

, or other agent CLIs aren't found, run the binary directly:

./target/release/opensquirrel

Configuration

Config file lives at

~/.opensquirrel/config.toml

~/.opensquirrel/state.json

Full config.toml example

[settings]
theme = "midnight"          # midnight | charcoal | gruvbox | solarized-dark | light | solarized-light | ops | monokai-pro
font_size = 14
compact_context = false

[[runtimes]]
name = "claude"
binary = "claude"           # must be on PATH when running the binary directly
mode = "persistent"         # persistent stdin (multi-turn)
permission_flags = ["--dangerously-skip-permissions"]

[[runtimes]]
name = "codex"
binary = "npx"
args = ["codex"]
mode = "oneshot"
permission_flags = ["--dangerously-bypass-approvals-and-sandbox"]

[[runtimes]]
name = "cursor"
binary = "cursor-agent"
mode = "oneshot"
permission_flags = ["--yolo"]

[[runtimes]]
name = "opencode"
binary = "opencode"
mode = "oneshot"            # auto-approved in run mode

[[models]]
runtime = "claude"
model = "claude-opus-4-5"   # coordinator/primary
alias = "opus"

[[models]]
runtime = "claude"
model = "claude-sonnet-4-5" # worker/sub-agent
alias = "sonnet"

[[mcp_servers]]
name = "playwright"
args = ["npx", "@playwright/mcp@latest"]

[[mcp_servers]]
name = "browser-use"
args = ["uvx", "browser-use-mcp"]

[[machines]]
name = "local"
host = "localhost"

[[machines]]
name = "dev-box"
host = "192.168.1.100"
user = "ubuntu"
ssh_key = "~/.ssh/id_ed25519"
tmux_session = "opensquirrel"

Supported Runtimes

--dangerously-skip-permissions

--dangerously-bypass-approvals-and-sandbox

--yolo

run

Keybinds Reference

Enter

Escape

Cmd-N

Cmd-K

Cmd-F

Cmd-]

Cmd-[

Cmd-}

Cmd-{

Cmd-V

Cmd-=

Cmd--

Setup wizard navigation: Arrow keys to move,

Enter

Backspace

Tab

Shift-Tab

Architecture Overview

~7,200 lines of Rust across 3 files:
src/
  main.rs          — UI, agent lifecycle, rendering, keybinds, persistence
  lib.rs           — Line classification, markdown parsing, diff summarization, helpers
tests/
  state_tests.rs   — 30 integration tests (navigation, scrolling, themes, search, agent lifecycle)

Built on GPUI — the GPU-rendered UI framework from Zed, used as a standalone crate. Rendered via Metal on macOS.

Agent Layout Behavior

Agents auto-arrange based on count:

Coordinator / Worker Delegation Pattern

A primary "coordinator" agent (typically Claude Opus) can delegate focused sub-tasks to worker agents (typically Claude Sonnet). Workers return condensed results, not full transcripts.

Typical setup:

1. Cmd-N

   → Select runtime:

   claude

   , model:

   opus

   → this becomes your coordinator

2. Cmd-N

   → Select runtime:

   claude

   , model:

   sonnet

   → worker agent
3. In the coordinator pane, prompt it to delegate: "Spawn a worker to refactor the auth module and report back"

The coordinator issues structured sub-prompts; workers execute and summarize.

Remote Machine Targeting via SSH

Configure machines in

config.toml

[[machines]]
name = "gpu-server"
host = "10.0.0.50"
user = "ubuntu"
ssh_key = "~/.ssh/id_ed25519"
tmux_session = "opensquirrel-agents"

The agent CLI will run inside a tmux session on the remote host. Ensure the agent binary (

claude

npx codex

MCP Server Integration

MCP servers are passed directly as CLI args to agent runtimes. Select which MCP servers to attach per agent during the setup wizard.

[[mcp_servers]]
name = "playwright"
args = ["npx", "@playwright/mcp@latest"]

[[mcp_servers]]
name = "browser-use"
args = ["uvx", "browser-use-mcp"]

When an agent is created with Playwright attached, OpenSquirrel appends the MCP args to the agent's launch command automatically.

Persistent Sessions

Agent state survives app restarts:

• Transcripts and scroll positions stored in

  ~/.opensquirrel/state.json

• Pending (unsent) prompts are preserved
• Interrupted multi-turn sessions (Claude Code persistent mode) can be resumed

To manually clear state:

rm ~/.opensquirrel/state.json

Transcript Search

Cmd-F

Escape

Themes

Available themes:

midnight

charcoal

gruvbox

solarized-dark

light

solarized-light

ops

monokai-pro

Change via

Cmd-K

config.toml

[settings]
theme = "gruvbox"

Running the Test Suite

cargo test

Tests in

tests/state_tests.rs

Common Patterns

Start a 4-agent parallel session

1. cargo build --release && ./target/release/opensquirrel
2. Cmd-N → Claude (Opus) on local machine, no MCP  [coordinator]
3. Cmd-N → Claude (Sonnet) on local machine         [worker: backend]
4. Cmd-N → Codex on local machine                   [worker: frontend]
5. Cmd-N → OpenCode on local machine                [worker: tests]

Agents auto-arrange into a 2×2 grid. Focus coordinator pane and send a high-level task.

Target a remote GPU machine

1. Add machine to ~/.opensquirrel/config.toml
2. Cmd-N → select runtime → select machine: "gpu-server"
3. Agent runs inside tmux on the remote host

Attach a browser automation MCP server

1. Ensure [[mcp_servers]] entry exists in config.toml
2. Cmd-N → setup wizard → step "MCP Servers" → check "playwright"
3. Agent launched with Playwright MCP wired in

Compact context to reduce token usage

Cmd-K

Troubleshooting

Agent binary not found (

claude

npx

codex

• Run

  ./target/release/opensquirrel

  directly instead of via

  .app

  bundle
• Or set full paths in

  config.toml

  :

  binary = "/usr/local/bin/claude"

Remote SSH agent not connecting

• Test SSH manually:

  ssh -i ~/.ssh/id_ed25519 ubuntu@10.0.0.50

• Ensure

  tmux

  is installed on the remote host
• Verify agent CLI is on the remote machine's PATH

State file corruption after crash

rm ~/.opensquirrel/state.json
# OpenSquirrel will create a fresh state on next launch

Metal/GPU errors on startup

• Requires macOS with Metal support (macOS 10.14+, any Apple Silicon or Intel Mac with discrete/integrated GPU)
• OpenSquirrel does not support Linux or Windows

Build failures

rustup update stable
cargo clean
cargo build --release

Agents not receiving prompts in persistent mode

• Claude Code persistent mode uses stdin; ensure

  --dangerously-skip-permissions

  is set in config so it doesn't pause for approval prompts mid-session

Environment Variables

OpenSquirrel itself does not read API keys — those are consumed by the agent CLIs it launches. Ensure these are set in your shell environment before launching the binary:

export ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY        # for Claude Code
export OPENAI_API_KEY=$OPENAI_API_KEY              # for Codex
# Cursor Agent uses its own auth; log in via cursor CLI first