# Orclaw

> Self-hosted multi-agent orchestrator. Ship parallel GitHub issues with Claude — paid by your Pro plan, not the API.

- **Type:** MCP server
- **Install:** `agentstack add mcp-jaschez-orclaw`
- **Verified:** Pending review
- **Seller:** [jaschez](https://agentstack.voostack.com/s/jaschez)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jaschez](https://github.com/jaschez)
- **Source:** https://github.com/jaschez/orclaw

## Install

```sh
agentstack add mcp-jaschez-orclaw
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🐋 Orclaw 🦞

**Multi-agent delegation for solo developers.**
Ship features in parallel, paid by your Claude Pro subscription — not by API tokens.

[](LICENSE)
[](https://www.python.org/downloads/)
[]()

```bash
curl -fsSL https://raw.githubusercontent.com/jaschez/orclaw/main/install.sh | bash
```

---

## Demo

A walk through the dashboard with the demo seed loaded — status, layered
plan, tuning page (concurrency cap + Pro-plan budget), runs table,
events filter, controls, prompt editor, timers. Reproduce locally in
under a minute:

```bash
git clone https://github.com/jaschez/orclaw.git && cd orclaw
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e '.[dashboard]'
export ORCLAW_DATA_DIR=$(mktemp -d) ORCLAW_GITHUB_REPO=example/demo GITHUB_TOKEN=dummy
orclaw demo-seed && orclaw dashboard serve --port 8888
# → http://127.0.0.1:8888
```

Stills of the showcase screens

#### Orchestration plan
The Kahn-layered scheduler. Each row is a layer; chips are issues.
Green-arrow chips are next-to-dispatch. Layer N waits for Layer N-1
to finish.

#### Tuning
Edit the concurrency cap at runtime (no redeploy). Watch the
Pro-plan 5h budget gauge so you know when to dial up or down.

#### Prompt editor
Edit `implementer-comment.md` and `reviewer-comment.md` live. Saves
go through the overlay layer — git-tracked defaults stay clean.
Effective on the next orchestrator tick.

---

## What is this?

Orclaw is a self-hosted orchestrator that turns your GitHub issues into parallel work for Claude — paid through a single `$20/mo` Pro plan, **not** the metered API.

You write issues. Orclaw picks them in dependency order, fires up to **N** Claude implementers in parallel (each in its own PR), waits for CI, runs a reviewer pass, auto-merges what's clean, and surfaces the rest on a dashboard you can reach from your phone.

> **Why this is different.** Every "AI dev agent" you've seen burns API tokens — fast. A meaningful refactor easily costs $30–$50 in Sonnet calls. Orclaw routes the work through GitHub's native [`@claude` mention integration](https://github.com/anthropics/claude-code-action), which charges your **Claude Pro plan** instead. Result: 5–10 features shipped per day on the same flat $20.

## Features

|   | What you get |
|---|---|
| **Parallel batches** | Kahn-layered topological scheduler dispatches independent issues simultaneously. Layer N waits for layer N-1 to merge. |
| **Pro-plan billing** | Zero API tokens. All implementer + reviewer calls run as `@claude` mentions on issues/PRs, consumed by your existing Pro subscription. |
| **Reviewer agent** | Every PR gets a second Claude pass that approves, requests changes, or flags `requires-human-review`. Auto-merge only fires on `review:approved`. |
| **Web dashboard** | FastAPI + zero-dependency vanilla JS. Live state, layered plan visualization, controls (pause / skip / force tick), prompt editor, timer editor, quota gauge. Mobile-responsive. |
| **Telegram bot** | Notifications + bidirectional commands (`/status`, `/pause`, `/resume`, `/skip`). Run the engine from your phone. |
| **Overlay layer** | Edit prompts, systemd timers, and services live from the dashboard. Changes land in `/var/lib/orclaw/overrides/` — never touch git, never lost on redeploy. |
| **Auto-deploy on push** | Merge to `main` → self-hosted runner pulls, restarts, runs `doctor`. Telegram on rollback. |
| **Saturation alerts** | Hits the concurrency cap with pending work? Telegram pings once per episode (de-duped). |
| **SQLite-backed audit** | Every dispatch, review, label change, and dashboard write is an event in the local DB. Queryable from the dashboard or via the specialist MCP. |
| **Cloudflare Access** | Cookie auth in front of the dashboard, OAuth-SaaS in front of the specialist MCP. No public surface. |

## How it works

```mermaid
flowchart TB
    classDef gh fill:#1c1c1c,stroke:#00ff88,stroke-width:2px,color:#f5f5f5
    classDef engine fill:#0d0d0d,stroke:#00ff88,stroke-width:1.5px,color:#f5f5f5
    classDef runner fill:#0d0d0d,stroke:#00b860,stroke-width:1.5px,color:#f5f5f5
    classDef surface fill:#0d0d0d,stroke:#ffaa00,stroke-width:1.5px,color:#f5f5f5
    classDef you fill:#001a0d,stroke:#00ff88,stroke-width:2px,color:#00ff88

    GH["GitHub repoissues · PRs · labels"]:::gh

    subgraph VM["Orclaw VM · yours"]
      direction TB
      subgraph Core[" "]
        direction LR
        Engine["Engine coreplanner · orchestrator · pollbackshared SQLite"]:::engine
        Runner["Self-hosted GitHub Actions runnerclaude-code-action runs Claude on your Pro plan"]:::runner
      end
      Surfaces["Dashboard · Telegram bot · Specialist MCP"]:::surface
      Engine |"read · write"| Surfaces
    end

    You(("you")):::you

    GH -->|"1 · open issues and PRs"| Engine
    Engine -->|"2 · @claude implement / review"| GH
    GH -.->|"3 · webhook fires claude.yml"| Runner
    Runner -->|"4 · opens PR, writes labels"| GH
    Surfaces ==>|"5 · watch and steer"| You

    style VM fill:#1a1a1a,stroke:#2a2a2a,stroke-width:1px,color:#707070
    style Core fill:transparent,stroke:transparent,color:transparent
```

**The key insight**: GitHub's `@claude` action runs *on your self-hosted runner*, uses *your Pro-plan session*, and reports back via labels and PR state. Orclaw never calls the Anthropic API directly. It just orchestrates **when** and **what** to mention.

## Quickstart

### Option A — one-line install on a fresh Ubuntu 24.04 VM

```bash
curl -fsSL https://raw.githubusercontent.com/jaschez/orclaw/main/install.sh | bash
```

The installer:
1. Installs system deps (`python3.12`, `git`, `curl`, `unzip`, `deno`, `cloudflared`).
2. Creates the `orclaw` system user.
3. Clones this repo to `/opt/orclaw` and sets up a venv.
4. Walks you through an interactive config wizard (GitHub PAT, target repo, Telegram bot token, etc.).
5. Installs + enables all systemd units (orchestrator, planner, summary, dashboard).
6. Prints next steps: register the GitHub Actions runner, set up Cloudflare Tunnel.

Total time on a clean VM: **~5 minutes**.

### Option B — Proxmox cloud-init template

If you run [Proxmox VE](https://www.proxmox.com/en/proxmox-virtual-environment/overview)
(or any cloud-init host), use the canned template. `qm` is Proxmox's
VM-management CLI; `` is the numeric ID Proxmox assigns to each
VM (e.g. `100`, `101`, `9000` for templates — visible in the web UI or
via `qm list`).

```bash
# 1. Fill in your SSH key + secrets in the cloud-init file.
$EDITOR proxmox/user-data.yml

# 2. Make it available to Proxmox as a snippet.
cp proxmox/user-data.yml /var/lib/vz/snippets/orclaw-user-data.yml

# 3. Clone an Ubuntu 24.04 cloud-init template into a new VM.
#    9000 = the VMID of YOUR base template (build it once — see the
#    full guide). 101 = the VMID for the new Orclaw VM (any free ID).
qm clone 9000 101 --name orclaw-01 --full
qm set 101 --cicustom "user=local:snippets/orclaw-user-data.yml"
qm set 101 --ipconfig0 ip=dhcp --ciuser ubuntu

# 4. Boot. The VM autoprovisions in 3–4 minutes.
qm start 101
```

Full guide (including how to build the base template + non-Proxmox
hosts like Hetzner / EC2 / GCP): [`proxmox/README.md`](proxmox/README.md).

### Option C — local dev

```bash
git clone https://github.com/jaschez/orclaw.git
cd orclaw
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e '.[specialist,dashboard]'
cp .env.example .env  # then edit with your tokens
orclaw doctor         # verifies config + connectivity
orclaw orchestrator tick --apply
```

## Configuration

Orclaw reads from two places:

- **`/etc/orclaw/secrets.env`** (root-owned, mode 640) — `GITHUB_TOKEN`, `TELEGRAM_BOT_TOKEN`, etc.
- **`ORCLAW_*` env vars** — everything else: target repo, concurrency cap, log level, paths.

See [`.env.example`](.env.example) for the full reference. Minimum required:

```bash
ORCLAW_GITHUB_REPO=yourname/your-target-repo
GITHUB_TOKEN=ghp_xxx                          # PAT with 'repo' scope
ORCLAW_CONCURRENCY_MAX_IN_FLIGHT=2            # tune to your runner's RAM
ORCLAW_TELEGRAM_BOT_TOKEN=...                 # optional, enables /commands
ORCLAW_TELEGRAM_CHAT_ID=...                   # your numeric chat ID
```

## Dashboard

The web dashboard is the heart of day-to-day operation. Live screenshots in [`docs/dashboard.md`](docs/dashboard.md). It exposes:

- **State**: in-flight runs, concurrency cap, batch counts.
- **Orchestration plan**: layered batches with "next to dispatch" highlights.
- **Tuning**: edit concurrency cap (no redeploy), see Pro-plan 5h budget consumed.
- **Batches / Runs / Events**: filterable tables.
- **Controls**: pause, resume, force-tick, skip-issue, require-human-review.
- **Prompts editor**: edit `implementer.md` / `reviewer.md` live — overlay layer.
- **Timers & services editor**: add / edit / delete systemd units live (auto-reloads daemon).
- **Mobile-first**: burger nav under 768px.

Bind it behind Cloudflare Access for cookie-auth from your phone. Recipe: [`docs/dashboard.md`](docs/dashboard.md).

## Telegram bot

Add a bot via [@BotFather](https://t.me/BotFather), drop the token into `secrets.env`, restart `orclaw-telegram-bot.service`. Commands:

| Command | What it does |
|---------|---|
| `/status` | Inline summary: paused?, in-flight, pending batches, last tick result. |
| `/pause` | Sets the pause flag — no new dispatches. |
| `/resume` | Clears the pause flag. |
| `/skip ` | Marks an issue as `skipped` — won't be picked again. |
| `/help` | Lists everything. |

The bot also receives push notifications for: saturation, deploy success/failure, daily digest at 23:00 local, dashboard write actions (audit trail).

## Specialist MCP

For the moments when you want to *converse* with the engine instead of clicking, Orclaw ships an MCP server exposing 13 tools (`get_status`, `query_runs`, `force_tick`, `skip_issue`, …). Connect from:

- **Claude Code**: `claude mcp add orclaw-specialist https://your-domain/mcp`
- **claude.ai mobile/web**: Settings → Connectors → Add → paste the URL
- **Cursor / Cline / any MCP client**

The MCP server is gated by Cloudflare Access OAuth-SaaS — full setup in [`docs/specialist-mcp.md`](docs/specialist-mcp.md).

## Cost

| Item | Monthly |
|---|---|
| Claude Pro | $20 |
| Ubuntu VM (Hetzner CX22, Oracle Cloud Always Free, etc.) | $0–6 |
| GitHub Actions self-hosted runner | Free |
| Cloudflare Tunnel + Access (≤50 users) | Free |
| Telegram bot | Free |
| **Total** | **$20–26** |

Compare to: a single mid-sized refactor through the Sonnet API typically costs $30+. Orclaw lets you ship five of those a day on the same Pro plan.

## Project status

**Alpha — production-tested by the author, API surface still settling.**

What's stable:
- Orchestrator loop + planner (proven across 200+ dispatches)
- Dashboard (read + write + overlay layer)
- Telegram push notifications
- Auto-deploy + rollback
- Specialist MCP

What's in active development:
- Telegram bidirectional bot (commands implemented, hardening in progress)
- Proxmox template polish
- Multi-repo support (currently one target repo per instance)
- First-class Hetzner / EC2 install recipes

Issues + PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

## Documentation

Deep-dives live in [`docs/`](docs/):

- [`architecture.md`](docs/architecture.md) — Why this design, what each subsystem owns.
- [`deploy-quickstart.md`](docs/deploy-quickstart.md) — Fastest path from "fresh VM" to "first @claude dispatch".
- [`deployment.md`](docs/deployment.md) — Full deployment reference (Oracle / Hetzner / Proxmox).
- [`auto-deploy.md`](docs/auto-deploy.md) — How push-to-main auto-deploy works + rollback contract.
- [`batch-algorithm.md`](docs/batch-algorithm.md) — The Kahn layering with worked examples.
- [`dashboard.md`](docs/dashboard.md) — Dashboard guide + Cloudflare Access setup.
- [`specialist-mcp.md`](docs/specialist-mcp.md) — Connecting claude.ai / Claude Code as a remote MCP.
- [`telegram-bot.md`](docs/telegram-bot.md) — Bot setup + command reference.
- [`pro-plan-strategy.md`](docs/pro-plan-strategy.md) — Why the @claude routing works + budget math.
- [`token-budget.md`](docs/token-budget.md) — Estimating your 5h window usage.
- [`operations.md`](docs/operations.md) — Day-to-day runbook (pause, retry, replan).
- [`development.md`](docs/development.md) — Local dev loop, tests, lint.

## Architecture decisions (highlights)

- **SQLite, not Postgres.** One-writer workloads + we want zero ops. Backed up nightly to your storage of choice.
- **Self-hosted GitHub Actions runner on the same VM** so the `@claude` action consumes your Pro session, not the API.
- **Overlay layer** for dashboard writes — every edit lands outside the git tree so auto-deploy never overwrites it.
- **Cloudflare-managed identity.** Access cookies for the browser, OAuth-SaaS for MCP clients. No JWT verification or session handling in the app.
- **Telegram for ops, not for product.** It's the lowest-friction surface for "ship from the couch."

## License

MIT — see [LICENSE](LICENSE).

## Acknowledgements

Built on top of Anthropic's [`claude-code-action`](https://github.com/anthropics/claude-code-action), which is the magic that lets `@claude` on a GitHub issue translate into a working PR.

---

If Orclaw saves you an afternoon, **a [star](https://github.com/jaschez/orclaw)** is the cheapest way to say thanks.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jaschez](https://github.com/jaschez)
- **Source:** [jaschez/orclaw](https://github.com/jaschez/orclaw)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jaschez-orclaw
- Seller: https://agentstack.voostack.com/s/jaschez
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.