Orchestrator

A desktop app for orchestrating multiple Claude Code agents on a visual canvas.

Built with Tauri 2 (Rust) + Svelte 5 (TypeScript)

Getting Started · Documentation · Contributing · Report Bug

What It Does

Orchestrator gives you a visual canvas where each node is a live Claude Code agent. You can:

Spawn agents — each one runs the claude CLI in its own PTY terminal or chat session
Build workflows — wire agents together in DAGs (fork/join, conditional routing, sub-workflows)
Schedule runs — attach cron triggers to any workflow
Track history — every run is recorded; report cards show before/after metrics

Features

Infinite canvas — pan, zoom, drag agents; minimap for orientation
PTY terminals — full ANSI rendering per agent (custom VT100 renderer, no xterm.js)
Chat mode — claude -p subprocess with session continuity, token/cost tracking
Workflow engine — DAG state machine with Fork/Join, conditional edges, retries, sub-workflows
Cron scheduler — tokio-cron-scheduler-based, triggers any workflow on a schedule
Workflow memory — run history injected as context into subsequent runs
Report cards — structured before/after metric cards rendered per run
Deploy system — script or agent-based deploy, triggered from the review screen
Variables — global ${VAR_NAME} interpolation in workflow prompts
IPC hub — Unix socket message bus between agents
REST API — full HTTP API (port 47821) so agents can control the app via the orc CLI
Skills — assign markdown skill files to agents; auto-detected via file watcher
Permission sandbox — automatic deny-lists prevent agents from accessing each other's workspaces

Prerequisites

Tool	Version	Notes
Rust	stable	`rustup update stable`
Node.js	18+	`brew install node`
Claude Code CLI	latest	`npm install -g @anthropic-ai/claude-code`
macOS	13+	Linux/Windows also supported by Tauri 2

For macOS you may also need Xcode Command Line Tools:

xcode-select --install

Installation

From source

git clone https://github.com/fonsecabc/orchestrator.git
cd orchestrator
npm install
make build

This produces the native app binary. To install it system-wide:

make install     # builds + copies binary to /usr/local/bin/orchestrator

Development mode (hot reload)

make dev

Frontend hot-reloads via Vite; Rust backend rebuilds on file changes.

Running

orchestrator        # if installed via make install
# or
make run            # build + launch immediately
# or
make dev            # dev mode with hot reload

The app opens a 1400×900 window. On first launch it creates ~/.orchestrator/ with all required directories and config files.

Quick Tour

1. Create an agent

Click + in the sidebar Agents section, give it a name and role. The agent appears as a card on the canvas. Click it to open its terminal or chat panel.

2. Write the agent's identity

Every agent has a CLAUDE.md — its system prompt. Edit it from the gear icon on the agent card or from the sidebar. This is where you define what the agent knows and how it behaves.

3. Build a workflow

Switch to the Workflows tab. Create a workflow, then add nodes:

Start / End (required, one each)
Agent — runs a prompt against a specific agent
Fork — splits into parallel branches
Join — merges branches back
SubWorkflow — runs another workflow inline

Connect nodes with edges. Each edge can have a condition (always, on_signal, on_error). Agent nodes complete via keyword match, timeout, or manual advance.

4. Run a workflow

Click Run on a workflow. Watch nodes light up as they execute. Every agent node writes its full output to ~/.orchestrator/squad_runs/<run_id>/.

5. Review and deploy

After all nodes complete, the run enters Review mode. Inspect the report card, then choose:

Deploy — runs the deploy script/agent (if configured)
Retry — re-runs from the start with optional feedback injected

Core Concepts

PTY vs Chat mode

Each agent supports two interaction modes:

Mode	How	Best for
PTY	Spawns `claude` CLI in a full interactive terminal	Exploratory, tool-heavy work
Chat	`claude -p` subprocess with `stream-json` output	Workflow automation, token tracking

Workflows always use Chat mode per agent. PTY is for direct human interaction.

Completion signals

Agent nodes in workflows complete via:

keyword — auto-advances when output contains a specific string (e.g. [DONE])
timeout — auto-advances after N seconds
manual — requires POST /runs/:id/advance-node

Convention: agent prompts end with "Output [KEYWORD] when done. Stop immediately after."

Variables

Global variables in ~/.orchestrator/variables.json are interpolated in workflow prompts at runtime:

Analyze the data at ${DB_URL} and write results to ${OUTPUT_DIR}.

Manage via the gear icon → Variables, or via the REST API.

Skills

Skills are .md files in ~/.orchestrator/skills/. Assign a skill to an agent and Claude Code loads it automatically in that agent's session. Skills are domain knowledge references — schemas, API docs, procedures.

Built-in Assistant

A built-in assistant agent lives at ~/.orchestrator/assistant/ and has the orc CLI available. Use it (via the Chat panel in the sidebar) to manage the entire system through natural language.

The orc CLI is a bash REST client that talks to the app's API at port 47821:

export PATH="$HOME/.orchestrator/assistant:$PATH"

# Agents
orc agents list
orc agents create "Analyst" "Data analysis agent"
orc agents spawn <id>

# Workflows
orc workflows list
orc workflows create "My Pipeline"
orc workflows start <id>

# Runs
orc runs list
orc runs advance <run_id>
orc runs report <run_id> '{"title":"Results","metrics":[{"label":"Score","before":72,"after":81,"unit":"%"}]}'

# Variables
orc vars list
orc vars create "DB_URL" "postgresql://..."

# Crons
orc crons list
orc crons create "0 */6 * * *" <workflow_id>

Full reference is in src-tauri/assistant/CLAUDE.md.

WhatsApp Bridge

Get workflow notifications and approve/retry runs from your phone via WhatsApp.

Setup

cd whatsapp-bridge
npm install
npm run dev

On first run, scan the QR code with WhatsApp (Settings → Linked Devices → Link a Device). Configure recipients in the app: Menu → WhatsApp Bridge.

Commands

Reply to notifications from your phone:

Command	Action
`approve`	Deploy the latest reviewed run
`retry`	Re-run from start
`retry: <feedback>`	Re-run with feedback injected
`status`	List active runs
`help`	Show commands

Uses Baileys (free, no Meta Business API required). Credentials stored locally in ~/.orchestrator/whatsapp/.

REST API

An Axum HTTP server runs on port 47821 alongside the app. Full reference in CLAUDE.md. Quick summary:

GET    /agents                     List agents
POST   /agents                     Create agent
POST   /agents/:id/spawn           Spawn PTY
GET    /workflows                  List workflows
POST   /workflows/:id/start        Start workflow → {run_id}
POST   /runs/:id/advance-node      Advance node
POST   /runs/:id/approve           Approve review
POST   /runs/:id/report            Submit report card
GET    /variables                  List variables
POST   /crons                      Create cron

Configuration

Everything lives under ~/.orchestrator/:

~/.orchestrator/
├── orch.db                  # SQLite: status, messages, run history
├── agents/<uuid>/
│   ├── CLAUDE.md            # Agent identity (edit freely)
│   └── .claude/settings.json  # Skills + permissions
├── skills/                  # Available skills (*.md, file-watched)
├── squads.json              # Workflow definitions
├── crons.json               # Cron jobs
├── variables.json           # Global variables (KEEP SECRETS OUT OF GIT)
├── knowledge/               # Shared knowledge base
├── lib/orc-vars.sh          # Bash helper for agents
└── assistant/               # Built-in assistant workspace (auto-updated on launch)

See examples/ in this repo for sample agent prompts, workflow configurations, and a variables.json.example.

Examples

The examples/ directory holds optional starter files you can copy into ~/.orchestrator/:

examples/
├── agents/
│   └── reporter/            # Reference copy of the built-in Reporter identity
├── squads.json              # Empty placeholder (define workflows in the app or via REST)
├── crons.json               # Empty placeholder
└── variables.json.example   # Example variable names (replace with your own secrets)

Create workflows and agents in the app or with the orc CLI; use variables.json.example only as a template for naming conventions.

Build Commands

make dev        # Tauri dev server with hot reload
make build      # Release binary
make install    # Build + install to /usr/local/bin/orchestrator
make uninstall  # Remove installed binary
make run        # Build + run immediately

Architecture

Layer	Tech
Frontend	Svelte 5 (runes), TypeScript 5, Tailwind CSS 4.2
Backend	Rust, Tauri 2, Tokio
Database	SQLite (rusqlite 0.31, WAL mode)
Terminal	portable-pty 0.8, custom ANSI renderer (no xterm.js)
Scheduling	tokio-cron-scheduler 0.13
IPC	Unix sockets
HTTP	Axum 0.7
Build	Vite 6 + Cargo

Key decisions:

Dual storage: SQLite for runtime data + run history; JSON files for config (agents can edit directly)
PTY spawns claude CLI: each agent IS a Claude Code process; the app manages many instances
Chat mode via claude -p: stream-json output, session continuity via --resume session_id
Graph-based workflows: DAGs not linear steps; supports fork/join parallelism, conditional routing, auto-retry
Custom terminal renderer: full VT100/xterm ScreenBuffer with Catppuccin Mocha palette
Agent sandboxing: automatic deny-lists prevent agents from reading other agents' workspaces

Full architecture documentation is in CLAUDE.md.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github		.github
docs/plans		docs/plans
examples		examples
src-tauri		src-tauri
src		src
whatsapp-bridge		whatsapp-bridge
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
svelte.config.js		svelte.config.js
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

Orchestrator

What It Does

Features

Prerequisites

Installation

From source

Development mode (hot reload)

Running

Quick Tour

1. Create an agent

2. Write the agent's identity

3. Build a workflow

4. Run a workflow

5. Review and deploy

Core Concepts

PTY vs Chat mode

Completion signals

Variables

Skills

Built-in Assistant

WhatsApp Bridge

Setup

Commands

REST API

Configuration

Examples

Build Commands

Architecture

Contributing

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages