⚡🦀 OverClawck

Structured operating methodology for AI agents — as a CLI or as a library. Plan → Execute → Review → Report → Template.

OverClawck is Scrum for AI agents — a persistent process layer that structures how AI agents plan, track, review, and learn from complex work. The agent does the work. OverClawck structures how it happens.

The human touches the system twice. Approve the plan. Review the output. Everything between is autonomous but narrated.

Read the full philosophy →

The Five Phases

Every complex task follows this cycle. This is the OverClawck methodology.

| Phase | What Happens | Key Commands | |-------|-------------|--------------| | Plan | Decompose work into phases and tasks. Externalize the plan. | overclawck plan, overclawck_create_plan | | Execute | Agent works through tasks, reporting progress. Agent drives — OverClawck records. | overclawck task-start, task-complete, task-fail, task-skip | | Review | Holistic review of all outputs. Cross-reference, verify, fix. | overclawck plan-review, overclawck snapshot | | Report | Postcomputation report: duration, cost, outcomes, lessons. | overclawck plan-complete | | Template | Save successful plans as reusable templates. Methodology compounds. | overclawck template-save, plan-from-template |

What v0.2.2 Adds

• Task lifecycle — task-start, task-complete, task-fail, task-skip, task-note for agent-driven execution
• Plan review & completion — plan-review with progress percentages, plan-complete with postcomp reports
• Snapshots — Point-in-time plan progress snapshots
• Templates — Save completed plans as reusable templates, create new plans from templates
• Methodology framing — OverClawck is a structured operating methodology, not a job queue

Quick Start

Start here: The agent-driven task lifecycle (plan → approve → task-start → task-complete → plan-review → plan-complete) is the recommended path. Legacy autonomous execution and the job queue still work but are not the primary abstraction.

# Install
npm install -g overclawck

# Initialize
overclawck init

1. Create a plan

overclawck plan "Brand Launch" --phases "Research,Design,Implementation" --runtime openclaw
# => Plan created: a1b2c3d4-... (3 phases, 3 tasks)

2. Approve the plan

# Paste the plan ID from the output above
overclawck approve a1b2c3d4-...
# => Plan approved. 3 tasks ready.

3. Work through tasks

# List tasks to find their IDs
overclawck plan-status a1b2c3d4-...
# => Phase 1: Research
# =>   [pending] e5f6a7b8-...  Research

# Start, do the work, complete
overclawck task-start e5f6a7b8-...
# ... agent does the work ...
overclawck task-complete e5f6a7b8-... --summary "Completed brand research"

4. Review and complete

overclawck plan-review a1b2c3d4-...
# => Progress: 1/3 tasks complete (33%)

# After all tasks are done:
overclawck plan-complete a1b2c3d4-...
# => Postcomp report generated.

5. Save as template for reuse

overclawck template-save a1b2c3d4-... "brand-launch"
# Next time: overclawck plan-from-template brand-launch "Q2 Brand Refresh"

Legacy job queue (still supported):

overclawck queue "Research grants" "Find NEA grants for sustainability nonprofits" --runtime openclaw
overclawck serve --start

End-to-End Example

A full methodology cycle for launching a blog — from plan creation through template extraction.

# 1. Initialize (if you haven't already)
overclawck init
# => Created .overclawck/config.json
# => Created .overclawck/overclawck.db

# 2. Create a plan with three phases
overclawck plan "Blog Launch" --phases "Research,Draft,Review"
# => Plan created: 7f3a91c2-4e8b-4d1f-b6a5-9c2d3e4f5a6b
# =>   Phase 1: Research (1 task)
# =>   Phase 2: Draft (1 task)
# =>   Phase 3: Review (1 task)

# 3. Approve the plan
overclawck approve 7f3a91c2-4e8b-4d1f-b6a5-9c2d3e4f5a6b
# => Plan "Blog Launch" approved. 3 tasks ready.

# 4. Check plan status to see task IDs
overclawck plan-status 7f3a91c2-4e8b-4d1f-b6a5-9c2d3e4f5a6b
# => Plan: Blog Launch [running]
# => Phase 1: Research
# =>   [pending] a1b2c3d4-1111-2222-3333-444455556666  Research
# => Phase 2: Draft
# =>   [pending] a1b2c3d4-2222-3333-4444-555566667777  Draft
# => Phase 3: Review
# =>   [pending] a1b2c3d4-3333-4444-5555-666677778888  Review

# 5. Start the first task
overclawck task-start a1b2c3d4-1111-2222-3333-444455556666
# => Task "Research" started.

# 6. (Agent does the research work here)

# 7. Add a progress note mid-task
overclawck task-note a1b2c3d4-1111-2222-3333-444455556666 "Found 5 competitor blogs, analyzing gaps"

# 8. Complete the task with a summary
overclawck task-complete a1b2c3d4-1111-2222-3333-444455556666 --summary "Found 5 competitor blogs, identified 3 content gaps"
# => Task "Research" completed.

# 9. Continue with remaining tasks...
overclawck task-start a1b2c3d4-2222-3333-4444-555566667777
# (write the draft)
overclawck task-complete a1b2c3d4-2222-3333-4444-555566667777 --summary "Drafted 3 blog posts targeting identified gaps"

overclawck task-start a1b2c3d4-3333-4444-5555-666677778888
# (review the drafts)
overclawck task-complete a1b2c3d4-3333-4444-5555-666677778888 --summary "All posts reviewed, minor edits applied"

# 10. Review progress
overclawck plan-review 7f3a91c2-4e8b-4d1f-b6a5-9c2d3e4f5a6b
# => Plan: Blog Launch
# => Progress: 3/3 tasks complete (100%)
# => All phases complete.

# 11. Complete the plan — generates a postcomp report
overclawck plan-complete 7f3a91c2-4e8b-4d1f-b6a5-9c2d3e4f5a6b
# => Plan "Blog Launch" completed.
# => Duration: 45m
# => Tasks: 3 completed, 0 failed, 0 skipped
# => Postcomp report saved.

# 12. Save as a reusable template
overclawck template-save 7f3a91c2-4e8b-4d1f-b6a5-9c2d3e4f5a6b "blog-launch"
# => Template "blog-launch" saved.
# Next time: overclawck plan-from-template blog-launch "Q2 Blog Sprint"

How It Works

Agent-Driven Execution (v0.2.2 — Recommended)

Human creates plan          →  overclawck plan "Project" --from-file plan.json
Human approves plan         →  overclawck approve <plan-id>
Agent starts a task         →  overclawck task-start <task-id>
  └─ Agent does the work    →  (in its own session, with full context)
  └─ Agent reports progress →  overclawck task-note <task-id> "progress update"
Agent completes task        →  overclawck task-complete <task-id> --summary "done"
  └─ Repeat for each task
Agent reviews holistically  →  overclawck plan-review <plan-id>
Agent completes plan        →  overclawck plan-complete <plan-id>
Human reviews output        →  overclawck snapshot <plan-id>

Autonomous Execution (Legacy — Still Supported)

Human creates plan          →  overclawck plan "Project" --from-file plan.json
Human approves plan         →  overclawck approve <plan-id> --auto-execute
AI executes autonomously    →  Phases run sequentially, tasks run in parallel
  └─ Live progress streams  →  channel_notify_url receives updates
  └─ Phase self-review      →  AI reviews output, replans if needed
Human reviews output        →  overclawck plan-status <plan-id>

Queue jobs via MCP, CLI, or API

Via MCP (Claude Code, Cline, Cursor, OpenClaw):

Add to your MCP config:

{
  "overclawck": {
    "command": "npx",
    "args": ["-y", "overclawck", "mcp"]
  }
}

Available MCP tools:

Job Queue:

• overclawck_queue_job / overclawck_queue_batch — Queue jobs
• overclawck_status / overclawck_get_job / overclawck_list_jobs
• overclawck_pause_job / overclawck_resume_job / overclawck_cancel_job
• overclawck_engine_control — Start/stop the engine

Plan Lifecycle:

• overclawck_create_plan — Create a project plan with phases and tasks
• overclawck_approve_plan — Approve a draft plan
• overclawck_plan_status — Get detailed plan progress
• overclawck_list_plans — List plans with filters
• overclawck_cancel_plan — Cancel a running plan
• overclawck_review_plan — Review plan progress with completion percentage
• overclawck_complete_plan — Complete a plan and generate postcomp report
• overclawck_snapshot — Get point-in-time plan progress snapshot

Task Lifecycle:

• overclawck_task_start — Start a pending task
• overclawck_task_complete — Complete a running task with summary
• overclawck_task_fail — Fail a running task with reason
• overclawck_task_skip — Skip a pending task with reason
• overclawck_task_note — Add a note to a task

Templates:

• overclawck_template_save — Save a plan as a reusable template
• overclawck_template_list — List saved templates
• overclawck_plan_from_template — Create a new plan from a template

Two-phase retry on failure

Phase 1 — Standard Retry (3x default): Same prompt, exponential backoff. Handles transient failures.

Phase 2 — Diagnosis Retry (3x default): Wraps the original prompt with error context and asks the agent to try a different approach. Error is truncated to 2000 chars to prevent prompt snowballing.

Supported Runtimes

| Runtime | Command | Use Case | |---------|---------|----------| | openclaw | openclaw run --prompt "..." | OpenClaw AI gateway | | claude-code | claude -p "..." | Claude Code CLI | | gemini-cli | gemini -p "..." | Gemini CLI | | codex-cli | codex -q "..." | OpenAI Codex CLI | | shell | /bin/bash -c "..." | Raw shell commands | | http | POST to URL | HTTP API calls |

CLI Commands

# Setup
overclawck init                          # Create .overclawck/ directory
overclawck serve                         # Start server + dashboard
overclawck serve --start                 # Start server with engine auto-running
overclawck mcp                           # Start MCP server (stdio)

# Jobs (legacy queue)
overclawck queue <name> <prompt>         # Queue a job
overclawck status                        # Show queue stats + active plans
overclawck list                          # List all jobs
overclawck list --status failed          # List failed jobs
overclawck log <job-id>                  # Show full job output
overclawck log <job-id> --tail 50        # Show last 50 lines
overclawck run                           # Process queue then exit
overclawck export                        # Export jobs to JSON
overclawck purge --status completed      # Delete completed jobs
overclawck purge --older-than 30         # Delete jobs older than 30 days

# Plans
overclawck plan <name> --phases "A,B,C"  # Create plan with stub phases
overclawck plan <name> --from-file p.json # Create plan from JSON
overclawck approve <plan-id>             # Approve plan (agent-driven execution)
overclawck approve <plan-id> --auto-execute # Approve and auto-execute (legacy)
overclawck plans                         # List all plans
overclawck plans --status running        # List running plans
overclawck plan-status <plan-id>         # Detailed plan progress

# Task Lifecycle
overclawck task-start <task-id>          # Start a pending task
overclawck task-complete <task-id>       # Complete a running task
overclawck task-fail <task-id>           # Fail a running task
overclawck task-skip <task-id>           # Skip a pending task
overclawck task-note <task-id> <note>    # Add a note to a task

# Plan Lifecycle
overclawck plan-review <plan-id>        # Review plan progress
overclawck plan-complete <plan-id>      # Complete plan + postcomp report
overclawck snapshot <plan-id>           # Point-in-time progress snapshot

# Templates
overclawck template-save <plan-id> <name>    # Save plan as template
overclawck template-list                      # List saved templates
overclawck plan-from-template <template> <name> # Create plan from template

Programmatic Usage (SDK)

OverClawck exports its core classes for use as a library:

import { OverClawck, PlanEngine } from 'overclawck';

// Initialize the engine
const engine = new OverClawck({ dbPath: '.overclawck/overclawck.db' });
await engine.ready();

// Create a plan programmatically
const plan = engine.createPlan({
  name: 'Automated Pipeline',
  phases: [
    { name: 'Extract', tasks: [{ name: 'Pull data', prompt: '...' }] },
    { name: 'Transform', tasks: [{ name: 'Clean data', prompt: '...' }] },
  ],
});

// Available exports:
// OverClawck, OverClawckDB, PlanEngine, RuntimeExecutor,
// ProgressStreamer, createServer, startMCPServer, and all types

REST API

| Method | Endpoint | Description | |--------|----------|-------------| | Jobs | | | | POST | /api/queue | Queue a new job | | POST | /api/complete | Complete a job (external) | | GET | /api/jobs | List jobs (with filters) | | GET | /api/jobs/:id | Get job details | | GET | /api/jobs/:id/log | Get job execution log | | GET | /api/jobs/:id/output | Get full job output | | GET | /api/running | Get running jobs | | POST | /api/jobs/:id/pause | Pause a job | | POST | /api/jobs/:id/resume | Resume a paused job | | POST | /api/jobs/:id/cancel | Cancel a job | | DELETE | /api/jobs/purge | Purge jobs (query: status, before, older_than) | | Plans | | | | POST | /api/plans | Create plan (PlanInput body) | | GET | /api/plans | List plans (query: status, project, client) | | GET | /api/plans/:id | Get plan + phases + tasks | | POST | /api/plans/:id/approve | Approve plan | | POST | /api/plans/:id/cancel | Cancel running plan | | GET | /api/plans/:id/log | Get progress event log | | GET | /api/plans/:id/review | Review plan progress | | POST | /api/plans/:id/complete | Complete plan + postcomp report | | GET | /api/plans/:id/snapshot | Point-in-time snapshot | | Tasks | | | | POST | /api/tasks/:id/start | Start a pending task | | POST | /api/tasks/:id/complete | Complete a running task | | POST | /api/tasks/:id/fail | Fail a running task | | POST | /api/tasks/:id/skip | Skip a pending task | | POST | /api/tasks/:id/note | Add a note to a task | | Templates | | | | POST | /api/templates | Save a plan as template | | GET | /api/templates | List saved templates | | POST | /api/plans/from-template | Create plan from template | | Engine | | | | POST | /api/engine/start | Start the engine | | POST | /api/engine/stop | Stop the engine | | GET | /api/stats | Queue statistics | | GET | /api/health | Health check | | GET | /api/export | Export jobs as JSON |

Architecture

                    ┌─────────────────────────────────────────────┐
                    │              Human                          │
                    │   1. Approve Plan    2. Review Output       │
                    └──────┬──────────────────────▲───────────────┘
                           │                      │
                    ┌──────▼──────────────────────-┤───────────────┐
                    │        OverClawck Methodology                │
                    │                                              │
                    │  ┌─ PLAN ─────────────────────────────┐     │
                    │  │  Phases, tasks, dependencies        │     │
                    │  └────────────────────────────────────-┘     │
                    │           ▼                                   │
                    │  ┌─ EXECUTE ──────────────────────────┐     │
                    │  │  Agent-driven (v0.2.2):             │     │
                    │  │    task-start → work → task-complete │     │
                    │  │  Autonomous (legacy):                │     │
                    │  │    Engine dispatches to runtimes     │     │
                    │  └────────────────────────────────────-┘     │
                    │           ▼                                   │
                    │  ┌─ REVIEW ───────────────────────────┐     │
                    │  │  plan-review, snapshot               │     │
                    │  └────────────────────────────────────-┘     │
                    │           ▼                                   │
                    │  ┌─ REPORT ───────────────────────────┐     │
                    │  │  plan-complete → postcomp report     │     │
                    │  │  Clawck time entries (auto)          │     │
                    │  └────────────────────────────────────-┘     │
                    │           ▼                                   │
                    │  ┌─ TEMPLATE ─────────────────────────┐     │
                    │  │  template-save → plan-from-template  │     │
                    │  │  Methodology compounds over time     │     │
                    │  └────────────────────────────────────-┘     │
                    │                                              │
                    └──────────────────────────────────────────────┘

overclawck/
  src/
    core/          → Types, database, engine, executor, planner, progress
    server/        → REST API (Express) + MCP server (stdio)
    dashboard/     → Single-file HTML dashboard
    cli/           → Command-line interface
  .overclawck/
    config.json    → Your configuration
    overclawck.db  → SQLite database

Design principles:

• Zero external deps — SQLite embedded, no Redis/Docker needed
• One process — API, dashboard, engine, and MCP from one overclawck serve
• Agent-driven — The agent does the work and reports to OverClawck, not the other way around
• Multi-runtime — Pluggable dispatch to any CLI tool or HTTP endpoint (legacy mode)
• Two-phase retry — Standard retry + diagnosis retry before giving up
• Plan-Execute-Review-Report-Template — The five-phase methodology at every level
• Composable — Pairs with Clawck (time tracking) and Pruuf (outcome tracking)

Configuration

Edit .overclawck/config.json:

{
  "port": 3457,
  "poll_interval": 15,
  "max_concurrent": 4,
  "default_runtime": "openclaw",
  "runtimes": {
    "openclaw": { "command": "openclaw", "args": ["run"], "timeout": 600 },
    "claude-code": { "command": "claude", "args": ["-p"], "timeout": 600 }
  },
  "clawck": { "enabled": false, "url": "http://localhost:3456", "default_category": "other", "auto_log": false },
  "spend_limits": { "enabled": false, "max_per_job": 5.0, "max_per_day": 50.0 },
  "notifications": { "webhooks": [], "notify_on": ["completed", "failed"] },
  "channel_notify_url": "",
  "workspace": "",
  "session_id": "",
  "retry_base_delay": 5000
}

Recommended: Set "auto_log": true in the clawck config to automatically create Clawck time entries for every task completion. This becomes the default in v0.3.0.

Clawck Integration

Enable automatic time tracking for every job:

{ "clawck": { "enabled": true, "url": "http://localhost:3456", "auto_log": true } }

Every job and task automatically gets a Clawck time entry: timer starts when the work begins, stops when it completes or fails.

Stability

Honest accounting of what works, what's new, and what's vaporware.

Stable

Battle-tested across real projects. Trust these.

| Feature | Since | Notes | |---------|-------|-------| | Job queue (queue, list, status, log) | v0.1.0 | Core loop. Works. | | Dependency chaining | v0.1.0 | Jobs wait for predecessors. Proven in 16-min autonomous runs. | | Multi-runtime dispatch | v0.1.0 | OpenClaw, Claude Code, Gemini, Codex, shell, HTTP. | | Two-phase retry | v0.1.0 | Standard retry + diagnosis retry. Prevents prompt snowballing. | | SQLite persistence | v0.1.0 | Zero-config, embedded. No Redis, no Docker. | | REST API | v0.1.0 | Express. All endpoints tested. | | MCP server | v0.1.0 | stdio. Works in Claude Code, Cline, Cursor, OpenClaw. | | CLI | v0.1.0 | Full command set. | | Plans with phases | v0.2.0 | Sequential phases, parallel tasks within phases. | | Live progress streaming | v0.2.1 | One-way updates to channel_notify_url. |

Experimental

Code exists. Tests pass (203/203). Used internally. But these are weeks old, not months — expect rough edges.

| Feature | Since | Honest Assessment | |---------|-------|-------------------| | Task lifecycle (start/complete/fail/skip/note) | v0.2.2 | The methodology pivot. Agent-driven instead of engine-driven. Works in tests and internal use. Not yet validated across diverse real-world projects. | | Plan review & completion | v0.2.2 | Postcomp reports generate correctly. Whether the reports are useful depends on how disciplined the agent is about summaries. | | Snapshots | v0.2.2 | Point-in-time views. Simple feature, low risk. | | Templates | v0.2.2 | Save/list/create-from-template works. Template quality depends entirely on the source plan — garbage in, garbage out. | | Autonomous plan execution (--auto-execute) | v0.2.0 | Spawns cold-started agents via shell. Works but violates the philosophy — the agent loses context. Kept as escape hatch, not recommended path. | | Dashboard | v0.2.0 | Single-file HTML. Functional, not pretty. Shows jobs and stats. Doesn't yet show plans or tasks. | | Spend limits | v0.1.0 | Config exists. Enforcement is basic. Don't bet your budget on it. | | Cron/recurring jobs | v0.1.0 | Pattern parsing works. Long-running cron reliability is untested beyond hours. | | Cost/token tracking | v0.1.0 | Fields exist. Spend limit (max_per_day) enforces. But the executor doesn't parse costs from runtimes — values stay 0 unless set externally via the complete() API. max_per_job is defined but not enforced. Treat as plumbing, not a feature. |

Planned

Not built. No code. Just intent.

| Feature | Target | Reality Check | |---------|--------|---------------| | Multi-agent coordination | v0.3.0 | The big vision — multiple AI tools reporting into shared plans. Architecture is clear but implementation is non-trivial. | | auto_log: true default | v0.3.0 | Trivial flip. Waiting for Clawck integration to be more widely tested first. | | Speculative execution | v0.3.0 | Competing approaches in parallel. Sounds cool. Resource implications are real. | | Sub-agent spawning | v0.3.0 | Letting agents spawn sub-agents within the methodology. Coordination complexity is high. | | Review-feedback loop | v0.3.0 | Agent reviews its own output and iterates. Risk of infinite loops if not bounded. | | Runtime capability matrix | v0.3.0 | Match tasks to runtimes by capability. Useful but not urgent. | | Hierarchical orchestration | v0.3.0 | Partner agents coordinating across organizations. Way out there. | | Pruuf integration | TBD | Outcome tracking. Pruuf itself doesn't exist yet. |

Roadmap

v0.3.0

• auto_log: true becomes the default
• Multi-agent coordination — shared plans across OpenClaw, Claude Code, Cursor, and client-deployed agents
• Speculative execution (competing approaches in parallel)
• Sub-agent spawning
• Review-feedback loop
• Auto-serve preview
• Runtime capability matrix
• Retry budget per phase
• Hierarchical orchestration (partner agents)

Philosophy

OverClawck encodes a bet: the agents that will dominate aren't the smartest ones — they're the most disciplined ones. Intelligence is commoditized. Process is not. OverClawck provides the externalized cognitive infrastructure that lets AI agents sustain complex work over days, weeks, and months.

Read the full philosophy →

The CubiCrew Toolbelt

| Tool | Purpose | Status | |------|---------|--------| | Clawck | Time tracking for AI agents | ✅ v0.1 | | OverClawck | Structured operating methodology for AI agents | ✅ v0.2.2 | | Pruuf | Outcome tracking | 🔜 Coming soon |

Together: OverClawck structures work → Clawck tracks time → Pruuf measures results.

License

MIT — use it, fork it, build on it.

Built by CubiCrew · Created by Vince Quarles