Turn GitHub Issues into a local agent queue. GitHub issues in, agent work out.
---
name: clawqueue
description: "Turn GitHub Issues into a local agent queue. GitHub issues in, agent work out."
homepage: https://github.com/ClawQueue/ClawQueue
metadata:
{
"openclaw":
{
"emoji": "๐ค",
"requires": { "bins": ["python3", "git"] },
},
}
---
# ClawQueue (CQ)

> **GitHub issues in ยท agent work out**
>
> Turn GitHub Issues into a local agent queue. ClawQueue is a local, git-backed and issue-tracked multi-agent queue manager designed for seamless human-agent collaboration.
---
## ๐ Core Value Proposition
ClawQueue replaces complex, centralized workflow orchestrators with a lightweight, git-native task queue. By using GitHub Issues and Project Boards as your control surface, you get full visibility, easy human-in-the-loop oversight, and standard Git auditing for free.
### Why Local-First?
- **No Agent Lock-In**: Run your workers locally, in isolated Docker containers, or as native OpenClaw subagents.
- **Standard Git Backing**: Every action, attempt, and deliverable is logged, tracked, and stored in standard Markdown and Mermaid files.
- **Zero Heavy Infra**: You don't need a heavy database or complex API endpoints. All state is modeled natively using Git branches, commits, and GitHub project columns.
---
## ๐ข The ClawQueue Organization Ecosystem
The complete ClawQueue suite is organized into specialized repositories under the [github.com/ClawQueue](https://github.com/ClawQueue) organization:
### โ๏ธ [ClawQueue/ClawQueue](https://github.com/ClawQueue/ClawQueue) (Core)
The main Python-based scheduler, dispatcher, and worker runtime. It polls your target project boards, matches unassigned issues in active column states (like "Todo"), triggers matching worker roles (e.g., `cto`, `cmo`), manages execution attempts, and commits results.
### ๐ [ClawQueue/ClawQueue-reports](https://github.com/ClawQueue/ClawQueue-reports) (The Worklog)
The standardized repository where completed task deliverables, automated reports, and execution artifacts live. Files are saved dynamically under `boards/<board_name>/<slug>.md` as structured Markdown files, ensuring your agent outputs are clean and public/private separated.
### ๐ณ [ClawQueue/openclaw-balena](https://github.com/ClawQueue/openclaw-balena) (Edge Deployment)
Shell scripts and container deployment configurations designed to run lightweight OpenClaw agent and node runtimes on [balenaOS](https://www.balena.io/). Perfect for deploying resilient agent worker nodes on physical edge devices and gateways.
### ๐ [ClawQueue/ClawQueue.github.io](https://github.com/ClawQueue/ClawQueue.github.io) (Documentation)
The official open-source documentation site. Hosted via GitHub Pages at [clawqueue.github.io/ClawQueue](https://clawqueue.github.io/ClawQueue/), it provides comprehensive guides, architecture overviews, and tutorials on starting your first dispatcher profile.
---
## ๐ How It Works
```
[ GitHub Project Board ]
โ
โผ (Polls columns: "Todo", "Ready")
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ClawQueue Scheduler โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ (Spawns isolated workers / subagents)
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ OpenClaw Worker Agents โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ (Generates deliverables and summaries)
[ ClawQueue-reports / Worklog Repo ]
โ
โผ (Updates board & closes issue)
[ Completed Issue / Board Column ]
```
---
## Common CLI Commands
Run these commands from your local ClawQueue repository root:
### View Status and Active Workers
Show active tasks, current PID, remaining attempts per issue, recent dispatch decisions, and matching queued items:
```bash
python3 scripts/status.py --profile <your-profile>
```
### Diagnostics and Verification
Diagnose local profile settings and verify that your configured repository pointers, scheduler service environment, and secret parameters are mapped correctly:
```bash
/cq diagnose
```
### Trigger Scheduler Runs
Trigger an immediate evaluation/run of the queue to process pending dispatches:
```bash
/cq run
```
### Resume or Retry Tasks
Retry a failed issue after clearing its attempt counts, or resume paused tickets:
```bash
/cq retry
```
### Pause or Block
Temporarily pause task board scheduling or suspend dispatches:
```bash
/cq pause
```
## Directory and File Mapping
- **Core Repository**: `~/ClawQueue` (or your chosen checkout path)
- **Reports and Deliverables**: `~/clawqueue-worklog`
- **Profile Configurations**: `./profiles/<profile>/config/`
- `workflow_policy.md` - Behavioral constraints and column mapping policies.
- `clawqueue.private.json` - Private API credentials, LLM keys, and local endpoint overrides.
- **Service Logs**: `~/.local/share/clawqueue/`
- **Scheduler State**: `~/.openclaw/tmp/clawqueue/`
don't have the plugin yet? install it then click "run inline in claude" again.