What is OpenAgents?

OpenAgents is a toolkit for running AI coding agents in parallel — each in its own git worktree, coordinated through your local OpenClaw gateway. It comes in two flavors:

| | CLI (oa) | Desktop (Tauri v2) | |---|---|---| | Install | npm i -g @openknot/openagents | Build from source | | Interface | Terminal + TUI | Native macOS app | | Agents | Codex, Claude, any gateway agent | Same | | Isolation | Git worktrees | Gateway sessions | | Extensions | MCP servers (stdio/HTTP) | Gateway tools |

Both connect to the same OpenClaw gateway — pick whichever fits your workflow.

Quick Start

CLI

# Install
npm install -g @openknot/openagents

# Configure gateway
oa config --url http://127.0.0.1:18789 --password yourpass

# Init a project
oa init OpenKnots/my-project

# Spawn an agent
oa spawn "fix the auth bug in src/auth.ts"

# Spawn three in parallel
oa parallel "add tests" "refactor the logger" "update docs"

# Interactive dashboard
oa ui

Desktop

cd desktop
pnpm install
pnpm tauri dev     # Development
pnpm tauri build   # Production (.app bundle)

Launch → enter gateway URL + password → select a repo → start spawning agents.

Desktop App

A native macOS app built with Tauri v2 + React 19. Dark, minimal UI inspired by Linear and Vercel.

Screens

| Screen | Purpose | |--------|---------| | Connect | Gateway URL + password, split hero layout | | Home | Raycast-style command input, agent pills, task suggestions | | Spawn | Pick an agent, write a task, launch | | Status | Live session list, agent states, gateway info | | Review | Worktree diffs (placeholder — wiring in progress) | | Extensions | MCP tool catalog from gateway |

Design

• Background: #0a0a0a — no pure black
• Surfaces: rgba(255,255,255,0.03) with rgba(255,255,255,0.06) borders
• No emoji icons anywhere — text-only navigation
• macOS traffic light buttons with 72px left spacer
• Font stack: Inter (body), SF Mono (code)

Building

cd desktop
pnpm install
npx tauri build --bundles app

Output: desktop/src-tauri/target/release/bundle/macos/OpenAgents.app

Requirements: Rust toolchain, Xcode Command Line Tools, Node.js 20+, pnpm

CLI Reference

Core Commands

| Command | Alias | Description | |---------|-------|-------------| | oa config | | Configure gateway connection | | oa connect | | Auto-detect local gateway | | oa init <source> | | Initialize a project | | oa spawn <task> | | Spawn an agent on an isolated worktree | | oa parallel <tasks...> | oa p | Spawn multiple agents in parallel | | oa decompose <task> | | Break a task into file-scoped subtasks | | oa ui | | Launch interactive TUI |

Review & PRs

| Command | Description | |---------|-------------| | oa review | Review diffs from all agent worktrees | | oa pr create | Create a PR from a worktree's changes | | oa pr review <n> | Review a GitHub PR by number |

Extensions (MCP)

| Command | Description | |---------|-------------| | oa ext ls | List MCP extensions | | oa ext add <name> | Add a stdio or HTTP MCP server | | oa ext probe <name> | Discover tools from an extension | | oa ext toggle <name> | Enable/disable an extension |

Workspace Management

| Command | Alias | Description | |---------|-------|-------------| | oa list | oa ls | List workspaces and agents | | oa status | oa st | Gateway connection + active agents | | oa rm <name> | | Remove a workspace |

Init Shorthands

oa init org/repo                 # GitHub (default)
oa init gh org/repo              # GitHub explicit
oa init gl group/project         # GitLab
oa init bb team/repo             # Bitbucket
oa init ~/code/my-project        # Local path
oa init https://github.com/...   # Full URL
oa init [email protected]:org/repo  # SSH URL

Spawn Options

# Default agent (codex)
oa spawn "fix the flaky test"

# One-shot mode (single pass, no follow-ups)
oa spawn --one-shot "fix the typo in README.md"

# Context pruning (ripgrep-powered focused context)
oa spawn --prune -w my-project "refactor auth"

# Auto-create PR on completion
oa spawn --auto-pr "fix the authentication bug"

# Specify agent + model
oa spawn -a claude -m anthropic/claude-opus-4 "refactor the DB layer"

Decompose

Break large tasks into file-scoped subtasks:

oa decompose "migrate from REST to GraphQL"
oa decompose --spawn "add rate limiting to all endpoints"

cmux Integration

If cmux is installed, --live opens agent output in split terminal panes:

oa spawn --live "fix the auth bug"
oa parallel --live "task 1" "task 2" "task 3"

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│  CLI (oa) or    │────▶│ OpenClaw Gateway  │────▶│  AI Agents  │
│  Desktop App    │◀────│  (your machine)   │◀────│ Codex, etc. │
└─────────────────┘     └──────────────────┘     └─────────────┘
        │                                              │
        ▼                                              ▼
┌──────────────┐                              ┌──────────────┐
│ Git Worktrees │                              │ MCP Extensions│
│  (isolated)   │                              │  (tools/APIs) │
└──────────────┘                              └──────────────┘
        │
        ▼
┌──────────────┐
│  PRs & Review │
└──────────────┘

How It Works

1. You describe tasks → OpenAgents creates isolated git worktrees
2. Agents spawn → Each gets its own branch via the gateway
3. Work in parallel → No conflicts, no stepping on each other
4. Review & merge → Check diffs, approve, create PRs

my-project/
├── .git/
├── .worktrees/
│   ├── agent/task-1-auth-fix/    ← Agent 1
│   ├── agent/task-2-add-tests/   ← Agent 2
│   └── agent/task-3-refactor/    ← Agent 3
└── src/                          ← Main branch untouched

Project Structure

OpenAgents/
├── src/                    # CLI source (~1800 lines)
│   ├── cli.ts              # Command definitions
│   ├── config.ts           # Configuration management
│   ├── onboarding.ts       # First-run setup
│   ├── agents/             # Agent runner + lifecycle
│   ├── context/            # Context pruning (ripgrep)
│   ├── decompose/          # Task decomposition
│   ├── extensions/         # MCP extension manager
│   ├── gateway/            # Gateway client + detection
│   ├── integrations/       # cmux terminal multiplexer
│   ├── review/             # Diff viewer + PR creation
│   ├── tui/                # Interactive terminal UI
│   └── workspace/          # Worktree manager + repo resolver
├── desktop/                # Desktop app (~2200 lines)
│   ├── src/
│   │   ├── App.tsx         # Main shell + tab router
│   │   ├── screens/        # Connect, Home, Spawn, Status, Review, Extensions
│   │   └── lib/            # Gateway client, hooks, design tokens
│   ├── src-tauri/          # Rust backend (Tauri v2)
│   └── public/             # Icons, logos, assets
├── assets/                 # Brand assets + hero image
├── docs/                   # Architecture docs
└── landing/                # Landing page

Gateway Protocol

Both CLI and desktop communicate with the OpenClaw gateway over WebSocket (protocol v3):

| Method | Description | |--------|-------------| | connect | Authenticate with password | | chat.send | Send a message / spawn an agent | | chat.history | Fetch session message history | | chat.abort | Cancel a running agent | | sessions.list | List active sessions | | agents.list | List available agents | | cron.list | List scheduled jobs | | tools.catalog | List available tool groups | | config.get | Read gateway configuration |

Comparison

| | OpenAgents | Codex (CLI) | Copilot Workspace | Cursor | |---|---|---|---|---| | Parallel agents | ✅ Unlimited | ❌ Single | ❌ Single | ❌ Single | | Git isolation | ✅ Worktrees | ❌ | ✅ Cloud | ❌ | | Local-first | ✅ Your machine | ✅ | ❌ Cloud | ❌ Cloud | | MCP extensions | ✅ | ❌ | ❌ | ❌ | | Desktop app | ✅ Native (Tauri) | ❌ | ❌ | ✅ Electron | | Open source | ✅ Apache-2.0 | ✅ | ❌ | ❌ |

Requirements

• Node.js 20+
• Git 2.20+ (worktree support)
• OpenClaw gateway (local or Tailscale)
• Rust toolchain (desktop app only)
• pnpm (desktop app only)

License

Apache-2.0