ClawQueue (CQ) is a local human-agent workflow engine for GitHub.

Combined with OpenClaw, CQ helps turn project context and operator intent into durable GitHub issues, then dispatches local agents to execute, report, and improve the work through reviewable GitHub history.

CQ is intentionally small: GitHub holds the durable work contract, OpenClaw helps shape the work, your machine runs the workers, and policy stays in markdown/config you can edit while using it.

CQ works in two very practical modes:

• operate your own company/project with your own profile, agents, boards, and worklog
• contribute to an external/open-source project through your fork by creating a project-specific CQ profile from the upstream repo’s README/docs/contribution rules, then routing issue-driven agent work into reviewed PRs

Use CQ when you want:

• human ideas and project context to become durable, reviewable GitHub work
• GitHub Projects to remain the visible queue and review surface
• local execution with operator-controlled secrets, approvals, and context
• profile-specific agents/modes without forking the core workflow
• a system that is easy to inspect, patch, and reshape while it is running
• a structured local workflow for contributing features/fixes to an external or open-source GitHub project through your fork
• OpenClaw to amplify rough operator intent into scoped issues, then CQ to carry those issues through execution and review

Use CQ with OpenClaw to absorb your project mission, docs, priorities, and current discussion into scoped GitHub work, then run your own agent team against your repos, boards, profiles, and worklog. This is the default operating model for internal product, growth, ops, research, and review work.

Use CQ as a local contribution pipeline for a repo you want to improve. OpenClaw reads the upstream project context; CQ makes the resulting work durable, queued, executable, and reviewable:

1. fork the target repo
2. create a project-specific CQ profile from the upstream README, docs, roadmap, and contribution rules
3. shape desired work into GitHub issues on your fork
4. let CQ dispatch local agent work against that project context
5. review the result and open a PR upstream

This gives you a durable GitHub-native agent workflow even when you do not “own the company” behind the repo.

Use OpenClaw to sharpen messy ideas, project goals, and half-formed feature requests into scoped issues; use CQ to route the work to specialist agents and keep artifacts/review history in GitHub instead of leaving everything trapped in chat.

Start with the docs, especially Getting started and the operator workflow.

flowchart TD
    A[Operator Intent & Docs] -->|1. Intake| B[OpenClaw Main Session]
    B -->|2. Shapes & Scopes| C[Durable GitHub Issue]
    C -->|3. Column State| D[GitHub Project Board / Queue]
    D -->|4. Polls & Schedules| E[ClawQueue Local Scheduler]
    E -->|5. Dispatches Workflow| F[OpenClaw Main Session]
    F -->|6. Spawns Isolated Subagents| G[OpenClaw Subagent Sandbox]
    G -->|7. Code / Review / QA| G
    G -->|8. Writes Double-Entry Log| H[Durable Worklog Repo / Artifacts]
    G -->|9. Creates PR & Comments| C
    C -->|10. Operator Approves| I[GitHub Main Branch]

The intended operating loop is:

1. Intake: OpenClaw reads the relevant project context, current conversation, and operator intent.
2. Scoping: A human or a chief-of-staff assistant turns that messy intent into a scoped, structured GitHub issue.
3. Queueing: GitHub Issues and Projects provide the shared queue, audit trail, and visible board state.
4. Scheduling: The ClawQueue scheduler scans eligible issues, resolves labels to specific profiles, and dispatches the task.
5. Execution (The OpenClaw Subagent Sandbox): ClawQueue starts an OpenClaw main session, which leverages OpenClaw's native orchestration engine to spawn isolated, task-specific subagents. These subagents carry out the execution (writing code, drafting documents, analyzing data) within secure, sandboxed environments.
6. Artifacting: The subagent commits its deliverables (artifacts) to a separate Git worklog repository, creating a double-entry accounting trail of all agent actions.
7. Delivery & Review: The subagent posts an execution report as a GitHub comment, opens a PR, transitions the board card to In Review, and awaits human sign-off.

Note: While ClawQueue can fall back to external CLI backends (like Claude Code or Codex), its primary execution substrate is the OpenClaw subagent runtime, ensuring high security, local-first tool execution, and rich cross-agent collaboration.

For multiple people, each person should run their own CQ/OpenClaw instance against the same GitHub boards, with their own accounts, secrets, approvals, and local context. By default CQ only dispatches Todo items. A deployment can opt into other dispatch statuses in its profile policy, but Review is usually a human/operator lane.

Human-agent work gets safer and easier to improve when intent, execution, and review are separated cleanly.

OpenClaw is good at understanding messy conversation, project context, and operator goals. GitHub is good at durable issues, boards, comments, PRs, and review history. CQ connects those two worlds with a small local control loop: shape the idea, queue the issue, dispatch the agent, preserve the result, review the outcome.

If OpenClaw, Claude Code, Codex, or a local machine breaks, times out, or changes, the work contract still lives in GitHub: issue text, labels, board state, comments, artifacts, and review history.

That makes CQ useful for operator-shaped teams and solo contributors who want agent-amplified GitHub work without burying their company workflow or open-source contribution process inside one chat, one PM surface, or one vendor runtime.

CQ overlaps with several agent-workflow tools, but it makes a different bet: keep GitHub as the durable workflow surface and keep the human-agent loop local, small, and operator-shaped.

The practical difference is resilience and operator control. Policy lives in markdown, routing lives in config, private IDs stay local, work lives in GitHub, and the operator can evolve the system without rebuilding a platform around it.

In one line: CQ is the GitHub-native control loop for human-agent work: understand the project, shape the idea, create the issue, dispatch the agent, and review the result without letting the work disappear into the runtime.

CQ core should stay generic. Company-specific mission, agent souls, routing, and deployment settings should live in a profile folder or private deployment repo. See the profiles guide.

Recommended shape:

profiles/<company-or-team>/
  COMPANY.md
  agents/
  modes/
  config/
  secrets/   # ignored/private by default

This keeps CQ easy to upgrade while private company context can evolve in its own git history.

Generated reports and research artifacts should not be mixed into product/profile PR branches. CQ defaults to ignored local artifacts under .clawqueue/boards; companies that want artifact history in git should use a second repo dedicated to worklog/artifacts. See the artifacts guide.

CQ works with the default GitHub Project status flow out of the box: Todo, In Progress, Done, with dispatch defaulting to Todo only. Teams that want a richer human-agent workflow can extend the board manually in the GitHub UI with statuses such as Inbox, Review, and Blocked. Bootstrap a new GitHub Project board with python3 scripts/bootstrap_project_board.py.

The scripts/scheduler.py entry point delegates to a small package:

Run the scheduler from cron, launchd, or another local scheduler:

python3 scripts/scheduler.py

On macOS, keep the repo in a non-privacy-protected path such as ~/ClawQueue; cron may be denied access to ~/Documents or ~/Desktop.

OpenClaw (chief of staff) — reads project docs, repo context, and human intent
  → drafts structured GitHub issues
  → human reviews and publishes issue to the queue

GitHub issue in Todo
  → scheduler entrypoint scans configured repos/projects
  → dispatcher picks an eligible issue
  → labels resolve to a mode and agent
  → issue is assigned and moved to In Progress
  → runner starts the selected backend:
      openclaw  →  openclaw agent --agent <name>
      claudecode →  claude -p <prompt> --print
      codex      →  codex -p <prompt>
  → worker comments completion  <!-- clawqueue:done -->
  → CQ moves completed work to Review and closes the GitHub issue
  → human reviews while closed, then either drags Review → Done or reopens in Review for revision
  → reopened Review issue is eligible for a reviewer/revision agent

ClawQueue decides which issue gets picked and which backend launches it. OpenClaw is usually upstream as the context-rich intake/chief-of-staff layer; when using the openclaw backend, it is also the runtime that launches the named specialist agent. With claudecode or codex, the runner passes the full task prompt directly to that CLI.

An issue is eligible when it is open, unassigned, on a configured board status listed in that project’s dispatch_statuses policy, under the attempt cap, and not blocked by locks, throttles, activity gates, or quota guards. The default policy is Todo only.

Recommended human-in-the-loop convention: closed + Review means “deliverable ready, human review pending, scheduler must wait”; open + Review means “changes requested, scheduler may revise”; closed + Done means “accepted/final.”

CQ uses both persistent agents and mode prompts:

• Agents are durable role specialists, especially when using the OpenClaw backend. A profile can define agents such as ceo, cto, and cmo, each with its own identity, soul, workspace, and memory.
• Modes are task lenses. They frame how a task should be approached and are injected into worker prompts. Modes are especially important for direct claude or codex runner calls, which should be treated as mostly stateless unless that runner provides its own session layer.
• Issues are the shared memory of work. CQ should not rely on one chat transcript or one agent's private memory to know what happened.

Recommended operating model: the main assistant acts as chief of staff for intake and synthesis, using project context to improve rough human ideas before they become issues; CQ dispatches those issues to persistent profile agents for execution; modes frame each task; issue comments and profile memory preserve the outcome.

Six named agents cover the full company operating surface:

Priority order: ceo › cto › reviewer › cmo › researcher › dev › engineer

• No mode label → routes to cto
• complex label → escalates to ceo
• All agents write a retrieval note to memory/notes/ after each task

Issue labels select the operating mode. Labels choose the cognitive mode; config resolves that role to one or more concrete OpenClaw agents. Board status decides whether the issue is ready.

Profiles should keep shared policy generic (ceo, cto, cmo, etc.) and map those roles to local runtime agent ids with routing.agent_roles, for example "cmo": ["manobot-cmo", "stratobot-cmo"]. CQ picks the first configured candidate. If an issue needs a specific runtime agent, add a label like agent:manobot-cmo to override role resolution directly for that issue.

Title: Draft a campaign brief for a new data product
Labels: cmo, marketing

Objective:
Draft a campaign brief for a clearly defined customer segment.

Acceptance criteria:
- Define audience and value proposition
- Draft campaign message
- Suggest 3 channels
- Include success metrics
- Mark external copy as draft-only

Title: Evaluate data quality for a customer-facing report
Labels: researcher, data-research

Objective:
Compare a sample dataset against credible references and summarize quality risks.

Acceptance criteria:
- Identify comparison sources
- Explain method, assumptions, and units where relevant
- Report uncertainty, limitations, and quality concerns
- Recommend the next validation step

Title: Add an active-worker status command
Labels: engineer, engineering

Objective:
Show the current active issue, repo, PID, and start time from local state.

Acceptance criteria:
- Handles missing or corrupt state
- Compile check passes
- No unrelated refactor

CQ is board-name agnostic. A deployment can define any ProjectV2 boards in its profile/config; the scheduler only needs the project number, ProjectV2 IDs, status field ID, and status option IDs.

A vanilla setup usually starts with 2-4 boards like these:

Keep these as examples, not CQ defaults. Real company board keys, titles, repo mappings, and ProjectV2 IDs belong in profiles/<company-or-team>/config/workflow_policy.md, ignored private config, or environment overrides.

ClawQueue supports three execution backends. Set runner_backend in the policy file or CLAWQUEUE_RUNNER_BACKEND env var.

When using claudecode or codex, the runner builds a full task prompt (including the mode instructions and acceptance criteria) and passes it directly to the CLI. OpenClaw is not involved at runtime — it is only needed upstream, as the chief of staff that drafts the issues.

# Use Claude Code CLI directly only after the local claude auth model is approved for this use
CLAWQUEUE_RUNNER_BACKEND=claudecode python3 scripts/scheduler.py

# Use Codex CLI directly only after local codex auth, quota, and account policy are understood
CLAWQUEUE_RUNNER_BACKEND=codex python3 scripts/scheduler.py

Minimal path:

1. Install/configure OpenClaw if using the openclaw runner backend.
2. Clone CQ.
3. Configure workflow policy in config/company_workflow_policy.md.
4. Put private IDs/secrets in config/clawqueue.private.json or environment variables.
5. Test manually:

python3 scripts/status.py --no-queue
python3 scripts/scheduler.py

6. Install the scheduler, preferably launchd on macOS:

python3 scripts/install_launchd.py --repo "$HOME/ClawQueue" --policy config/company_workflow_policy.md

Environment variables are escape hatches for local overrides. They are not the primary config mechanism for a single company instance.

Config loads in this order — later layers override earlier ones:

config/company_workflow_policy.md                    ← tracked generic default
profiles/<profile>/config/workflow_policy.md         ← tracked/shared profile policy when --profile is used
config/clawqueue.private.json                        ← gitignored generic private config
profiles/<profile>/config/clawqueue.private.json     ← gitignored per-user profile overrides
CLAWQUEUE_* env vars                                 ← rare one-off overrides

# generic/single-policy setup
cp config/clawqueue.private.example.json config/clawqueue.private.json

# shared profile setup
cp profiles/<profile>/config/clawqueue.private.example.json \
  profiles/<profile>/config/clawqueue.private.json
python3 scripts/status.py --profile <profile>
python3 scripts/install_launchd.py --repo "$HOME/ClawQueue" --profile <profile>

For multiple schedulers on one Mac, give each LaunchAgent its own label and wrapper name. The installer now writes per-label runtime isolation by default:

python3 scripts/install_launchd.py \
  --repo "$HOME/ClawQueue" \
  --profile weatherxm \
  --label com.clawqueue.weatherxm \
  --wrapper-name clawqueue-weatherxm.sh

Defaults are ~/.openclaw/tmp/clawqueue/<label> for CLAWQUEUE_STATE_DIR, ~/.local/share/clawqueue/<label> for CLAWQUEUE_LOG_DIR, and the active profile/policy config directory for CLAWQUEUE_PRIVATE_CONFIG_FILE. Override them explicitly with --state-dir, --log-dir, and --private-config when a deployment needs fixed paths.

• gh authenticated with access to configured repos and ProjectV2 boards
• Real repo names in private config or CLAWQUEUE_PRIMARY_REPO / CLAWQUEUE_EXTRA_REPOS
• Real ProjectV2 IDs and status option IDs for board status updates
• For openclaw backend: openclaw on PATH (or set CLAWQUEUE_OPENCLAW_COMMAND), and OpenClaw agents configured for ceo, cto, dev, cmo, researcher, reviewer
• For claudecode backend: claude CLI on PATH with an auth method explicitly approved for this CQ use case; API-key and subscription/session-backed setups have different policy and quota implications
• For codex backend: codex CLI on PATH with an auth method explicitly approved for this CQ use case; API-key and subscription/session-backed setups have different policy and quota implications
• Python available locally. Docs target Python 3.11+, but CQ may still run on older macOS system Python if your installed feature set is compatible; verify with the compile/test commands below.

Telegram, activity gates, quota tuning, mode URL overrides, and fallback maps are optional.

GitHub ProjectV2 mutations need node IDs that must not be committed. Put them in config/clawqueue.private.json:

{
  "github": {
    "assignee": "your-github-login"
  },
  "projects": {
    "MT": {
      "project_id": "<github-project-node-id>",
      "field_id": "<github-project-status-field-id>",
      "status_options": {
        "todo": "option-id-for-todo",
        "in_progress": "option-id-for-in-progress",
        "done": "option-id-for-done"
      }
    }
  }
}

Use CLAWQUEUE_PROJECTS_JSON for the same data in CI or a secret-managed runtime.

CQ stays local-first and solo-operator friendly, but it mirrors the useful state back to GitHub:

• one managed progress comment per issue, marked with <!-- clawqueue:progress -->
• tiny worker result comments, marked with <!-- clawqueue:result --> and <!-- clawqueue:done -->
• issue comments as simple commands: /cq diagnose, /cq run, /cq retry, /cq pause
• issue/comment text is treated as untrusted task data in worker prompts

Workers should not directly close issues or move board status. They report a small result object and CQ applies final state:

{
  "status": "done",
  "summary": "Brief operator-facing summary.",
  "files_changed": ["relative/path-or-github-url"],
  "needs_review": true
}

Supported commands:

CQ-owned state labels: cq:paused, cq:failed, cq:blocked.

CQ deliverable labels:

• cq:artifact — agent-side label for a durable Markdown/report/spec deliverable. Workers avoid product/source mutations unless the issue explicitly asks for them. Generated artifacts go to the configured local/worklog artifact destination, not into the code/profile PR branch.
• cq:change — agent-side label for a source/content/config/docs change deliverable with verification evidence.

Use exactly one deliverable label when possible. If missing, CQ infers one from the issue title/body and adds the inferred label before dispatch.

Company profile safety can restrict cq:change to trusted GitHub issue authors:

"safety": {
  "change_author_allowlist": ["github-user", "operator-alt"]
}

When the allowlist is set, CQ blocks unauthorized cq:change issues with cq:blocked before dispatch. cq:artifact remains suitable for broader intake.

Each scheduler run:

1. Trims the decision log to the configured retention window
2. Sweeps stale In Progress board items
3. Exits if another dispatcher or worker is active
4. Applies the throttle and attempt-count limits
5. Reads open issues from configured repos
6. Picks the highest-priority eligible issue from each project’s configured dispatch_statuses; issues with explicit depends on Issue #N / depends on #N lines wait until those dependencies have a completion result after their latest retry
7. Defaults to Todo only; profiles can opt into other statuses explicitly
8. Checks provider quota via codexbar when available, including Codex daily/primary and weekly/secondary remaining quota windows
9. Warns when configurable remaining-quota thresholds are crossed, then stops/reroutes if stop thresholds are crossed
10. Assigns the issue, moves it to In Progress, and starts the selected agent

Runtime state lives in CLAWQUEUE_STATE_DIR (default: temp dir named clawqueue; launchd installs use a per-label directory). Decision log persists under CLAWQUEUE_LOG_DIR (default: ~/.local/share/clawqueue; launchd installs use a per-label directory).

# Inspect recent decisions, active worker, attempt counts, queued issues
python3 scripts/status.py

ClawQueue assumes a trusted operator on a trusted local machine. It shells out to gh, codexbar, and openclaw. Do not expose it as a public service without authentication, authorization, command sandboxing, audit logging, and a proper secret manager.

Agents are internal team assistants. External-facing work is draft-only until a human approves it. Human approval is required before:

• Publishing, sending, pricing, or promising anything externally
• Outbound sales, partnerships, or official communications
• Commercial terms, legal/financial/regulatory claims
• Official roadmap commitments or company authority

Tracked files must not contain bot tokens, chat IDs, ProjectV2 node IDs, personal absolute paths, or private assignees. Run a local secret scan before sharing.

ClawQueue ships a compact design system for the operator UI — deep navy, precise typography, and an amber accent for agent activity. Open index.html in a browser for the full design system hub — colors, typography, spacing, and all components.

# Compile-check all Python
python3 -m py_compile scripts/scheduler.py clawqueue/*.py

# Run unit tests
python3 -m unittest

# Inspect before committing
git diff --stat && git diff