npm package: @openknot/openagents
Description: Parallel AI coding agents via OpenClaw gateway. Run dozens of agents across isolated worktrees.
Author: OpenKnots
Latest version: 0.4.1

<p align="center">
  <img src="assets/openagents-hero.jpg" alt="OpenAgents" width="520" />
</p>

<h3 align="center">Parallel AI coding agents — CLI + native desktop</h3>

<p align="center">
  Spawn dozens of agents across isolated git worktrees.<br/>
  No cloud. No Electron. Just your gateway and git.
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> •
  <a href="#desktop-app">Desktop App</a> •
  <a href="#cli-reference">CLI Reference</a> •
  <a href="#architecture">Architecture</a> •
  <a href="https://openclaw.ai">OpenClaw</a>
</p>

---

## 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](https://openclaw.ai) 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

```bash
# 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

```bash
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

```bash
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

```bash
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 git@github.com:org/repo  # SSH URL
```

### Spawn Options

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

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

### cmux Integration

If [cmux](https://cmux.dev) is installed, `--live` opens agent output in split terminal panes:

```bash
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](https://openclaw.ai)** gateway (local or Tailscale)
- **Rust toolchain** (desktop app only)
- **pnpm** (desktop app only)

## License

[Apache-2.0](LICENSE)

---

<p align="center">
  Built with <a href="https://openclaw.ai">OpenClaw</a> · <a href="https://github.com/OpenKnots">OpenKnots</a>
</p>