A coordination layer CLI for OpenClaw fleets that manages tasks, messaging, activity feed, and a dashboard.

How do I start using clawctl?

Run clawctl init to create the DB, set CLAW_AGENT and CLAW_DB, then follow the Operational Rhythm: checkin, inbox, next, claim, start, msg, and done.

How are tasks moved through statuses?

Tasks progress from pending to claimed to in_progress to done; blockers, reviews, and handoffs are supported via additional commands.

Clawctl

Scanned

@lludlow

npx machina-cli add skill @lludlow/clawctl --openclaw

Files (1)

SKILL.md

3.3 KB

Setup

clawctl init                        # create the database
export CLAW_AGENT=your-name         # set identity (falls back to $USER with warning)
export CLAW_DB=~/.openclaw/clawctl.db  # optional, this is the default

Operational Rhythm

Follow this pattern every session:

clawctl checkin — register presence, see unread count
clawctl inbox --unread — read messages before picking up work
clawctl next — find highest-priority actionable task (or clawctl list --mine)
clawctl claim <id> then clawctl start <id> — take ownership and begin
clawctl msg <agent> "update" --task <id> — coordinate during work
clawctl done <id> -m "what I did" then clawctl next — complete and move on

Only claim tasks assigned to you or matching your role. Completing an already-done task is a safe no-op.

Decision Tree

Situation	Command
New task	`clawctl add "Subject" -d "Details"`
Find work	`clawctl next` then `clawctl claim <id>`
Blocked	`clawctl block <id> --by <blocker-id>` and notify via `clawctl msg`
Finished	`clawctl done <id> -m "Result"`
Hand off	`clawctl msg <agent> "Ready for you" --task <id> --type handoff`
Ready for review	`clawctl review <id>`
Catch up	`clawctl feed --last 20` or `clawctl summary`
Link artifacts	Add `--meta '{"note":"path/to/file"}'` to `done`, `claim`, `start`, or `block`

Task Statuses

pending → claimed → in_progress → done
                  ↘ blocked ↗    ↘ cancelled
                  ↘ review  ↗

list excludes done/cancelled by default. Use --all for history (newest first).

Commands

Tasks

Command	Description
`add SUBJECT`	Create task. `-d` desc, `-p 0\|1\|2` priority, `--for AGENT` assign, `--parent ID`
`list`	Active tasks. `--mine`, `--status STATUS`, `--owner AGENT`, `--all`
`next`	Highest-priority actionable task for current agent
`claim ID`	Claim task. `--force` overrides ownership, `--meta JSON`
`start ID`	Begin work (in_progress). `--meta JSON`
`done ID`	Complete. `-m` note, `--force`, `--meta JSON`
`review ID`	Mark ready for review. `--meta JSON`
`cancel ID`	Cancel task. `--meta JSON`
`block ID --by OTHER`	Mark blocked. `--meta JSON`
`board`	Kanban board grouped by status

Messages

Command	Description
`msg AGENT BODY`	Send message. `--task ID`, `--type TYPE` (comment, status, handoff, question, answer, alert)
`broadcast BODY`	Alert all agents
`inbox`	Read messages. `--unread` for unread only

Fleet

Command	Description
`checkin`	Heartbeat — update presence, report unread count
`register NAME`	Register agent. `--role TEXT`
`fleet`	All agents with status and current task
`whoami`	Identity, role, and DB path

Monitoring

Command	Description
`feed`	Activity log. `--last N`, `--agent NAME`, `--meta`
`summary`	Fleet overview with counts and recent events
`dashboard`	Web UI. `--port INT`, `--stop`, `--verbose`

Source

git clone https://clawhub.ai/lludlow/clawctlView on GitHub

Overview

Clawctl provides a central coordination layer for an OpenClaw agent fleet, handling tasks, messaging, activity feed, and a web dashboard. It standardizes how agents check in, claim and work on tasks, communicate status, and review outcomes, improving transparency and throughput.

How This Skill Works

Clawctl runs as a CLI tool backed by a local database. Agents initialize with clawctl init and identify themselves via CLAW_AGENT, then follow a session rhythm: checkin, inbox, next, claim/start, and done, with messages during work. Tasks move through statuses: pending, claimed, in_progress, done, with blockers and review states tracked in the feed and dashboard.

When to Use It

New task creation and assignment
Finding the next actionable task for the agent
Handling blocked tasks and blockers with handoff
Completing work and moving to review
Reviewing or handing off completed work

Quick Start

Step 1: clawctl init; export CLAW_AGENT=your-name; export CLAW_DB=path/to/db
Step 2: Daily workflow — clawctl checkin; clawctl inbox --unread; clawctl next; clawctl claim <id>; clawctl start <id>; clawctl msg <agent> update --task <id>; clawctl done <id> -m 'what I did'
Step 3: Optional UI — clawctl dashboard --port 8080

Best Practices

Check in and read unread messages before choosing work
Only claim tasks assigned to you or matching your role
Coordinate with explicit messages during work and use handoff/review flows
Attach artifacts by adding --meta with a JSON payload to relevant commands
Use the dashboard and fleet feed to stay aligned and monitor progress

Example Use Cases

An agent checks in, reviews unread inbox, uses next to pick a high-priority task, claims and starts, communicates updates via msg, then uses done with a summary and moves on
When a task blocks, the agent runs block with --by and notifies the team via msg
Upon partial completion, the agent uses handoff messaging to hand the task off to the next agent
Artifacts are linked by adding --meta '{"note":"path/to/file"}' to the done command
To stay up to date, the agent runs feed --last 20 or summary to see fleet activity

Frequently Asked Questions

Add this skill to your agents