🦞 ClawTrol

Open source mission control for your AI agents.

ClawTrol is a kanban-style dashboard for managing AI coding agents. Track tasks, assign work to agents, monitor their activity in real-time, and collaborate asynchronously. Forked from ClawDeck with extended agent integration features.

🚧 Early Development — ClawTrol is under active development. Expect breaking changes.

Get Started

Self-host (recommended)
Clone this repo and run your own instance. See Self-Hosting below.

Contribute
PRs welcome! See CONTRIBUTING.md.

---

Features

🪝 Webhook Integration

• OpenClaw Gateway — Instant wake via webhook when tasks are assigned
• Real-time Triggers — No polling delay for agent activation

🔐 Security

• Command Injection Prevention — Validation commands sandboxed with Shellwords + allowlist
• API Token Hashing — Tokens stored as SHA-256 hashes, never plaintext
• AI Key Encryption — ai_api_key encrypted at rest with Rails credentials
• Settings Page — Tabbed layout (Profile / Agent / AI / Integration)

---

How It Works

1. You create tasks and organize them on boards.
2. You move work to up_next and assign it to the agent queue.
3. ClawTrol auto-runner wakes runnable work with nightly gating and in-progress guardrails (base cap 4, burst cap 8 only when queue pressure is high and no recent errors/rate-limits).
4. OpenClaw is the orchestrator: it picks claimed work, routes model/persona, and executes.
5. OpenClaw must always report structured outcome via POST /api/v1/hooks/task_outcome.
6. OpenClaw must always persist execution output via POST /api/v1/hooks/agent_complete.
7. Task moves to in_review; follow-up is YES/NO plus recommendation, never silent.
8. If follow-up is needed, requeue happens only after explicit human approval, using the same card (POST /api/v1/tasks/:id/requeue).
9. If no follow-up is needed, task remains in in_review and the human decides next action.

OpenClaw Onboarding and Self-Heal

• Main guide: docs/OPENCLAW_ONBOARDING.md
• Fast path in UI: Settings -> Integration -> Agent Install Prompt
• Contract summary:
  • OpenClaw executes work; ClawTrol stores state and reporting.
  • Every completed run sends both hooks: task_outcome then agent_complete.
  • Follow-up recommendation is mandatory (needs_follow_up: true|false).
  • Same-task follow-up is preferred to avoid kanban bloat.
  • Nightly window for Argentina: 23:00-08:00 (America/Argentina/Buenos_Aires, UTC-3).

Agent Install Prompt (OpenClaw / Telegram Orchestrator)

ClawTrol works best when your orchestrator has an explicit "tooling + reporting contract" prompt so it:

• knows which endpoints exist and how to authenticate
• always reports back deterministically at the end of each run
• can requeue the same task for follow-ups (no kanban bloat)

In your running instance, open http://<host>:<port>/settings → Integration and use Agent Install Prompt.

If you're integrating manually:

• API endpoints live under /api/v1/* (Bearer token)
• Completion hooks live under /api/v1/hooks/* (X-Hook-Token)
• Follow-up is signaled via POST /api/v1/hooks/task_outcome with recommended_action="requeue_same_task"

---

Tech Stack

• Ruby 3.3.1 / Rails 8.1
• PostgreSQL with Solid Queue, Cache, and Cable
• Solid Queue — Background jobs for validation, async processing, and webhook-driven workflows
• ActionCable — WebSocket for real-time kanban + agent activity
• Hotwire (Turbo + Stimulus) + Tailwind CSS v4
• Propshaft — Asset pipeline with importmap-rails
• 45+ Stimulus Controllers — Full client-side interactivity
• Authentication via GitHub OAuth or email/password
• Docker Compose — Production-ready setup with install.sh

---

Self-Hosting

Prerequisites

• Ruby 3.3.1
• PostgreSQL
• Bundler

Option A: Docker Compose (recommended)

git clone https://github.com/wolverin0/clawtrol.git
cd clawtrol
chmod +x install.sh
./install.sh

install.sh is safe to re-run and appends SECRET_KEY_BASE to .env.production only when missing.

Visit http://localhost:4001

Option B: Manual Setup

git clone https://github.com/wolverin0/clawtrol.git
cd clawtrol
bundle install
bin/rails db:prepare
bin/dev

Visit http://localhost:3000

Authentication Setup

ClawTrol supports two authentication methods:

1. Email/Password — Works out of the box
2. GitHub OAuth — Optional, recommended for production

GitHub OAuth Setup

1. Go to GitHub Developer Settings
2. Click New OAuth App
3. Fill in:
   • Application name: ClawTrol
   • Homepage URL: Your domain
   • Authorization callback URL: https://yourdomain.com/auth/github/callback
4. Add credentials to environment:

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

OpenClaw Integration

Configure webhook in Settings → OpenClaw Integration:

• Gateway URL: Your OpenClaw gateway endpoint
• Gateway Token: Your authentication token
• Agent Prompt: copy from Settings -> Integration -> Agent Install Prompt
• Onboarding + self-heal: docs/OPENCLAW_ONBOARDING.md

Running Tests

bin/rails test
bin/rails test:system
bin/rubocop

---

🤖 AI-Assisted Installation & Onboarding

Have an AI assistant with shell access (OpenClaw, Claude Code, Codex)? Give it the prompt below to install ClawTrol and fully configure itself as your agent — API tokens, webhook hooks, heartbeat polling, and auto-runner included.

---

One-Prompt Install

Copy this entire prompt to your AI assistant:

Install and configure ClawTrol (AI agent mission control) for me. Do ALL steps — don't stop until you've verified everything works.

Step 1 — Clone & Install

cd ~ && git clone https://github.com/wolverin0/clawtrol.git clawdeck
cd clawdeck
chmod +x install.sh && ./install.sh

If Docker isn't available, fall back to manual:

bundle install && bin/rails db:prepare && bin/dev

Step 2 — Wait for server

• Docker: port 4001
• Manual: port 3000
• Health check: curl -sf http://localhost:PORT/up (retry up to 30s)

Step 3 — Create user account

cd ~/clawdeck && bin/rails runner "
  User.create!(
    email: 'MY_EMAIL',
    password: 'MY_PASSWORD',
    name: 'MY_NAME'
  )
  puts '✅ User created'
"

Step 4 — Generate API token + Hooks token

cd ~/clawdeck && bin/rails runner "
  user = User.find_by!(email: 'MY_EMAIL')
  api_token = user.api_tokens.create!(name: 'Agent')
  puts 'API_TOKEN=' + api_token.token
  puts 'HOOKS_TOKEN=' + Rails.application.config.hooks_token.to_s
"

Save both tokens — the API token is only shown once.

Step 5 — Create a default board

curl -s -X POST http://localhost:PORT/api/v1/boards \
  -H "Authorization: Bearer API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Main", "icon": "🚀"}' | jq .

Step 6 — Configure yourself as the ClawTrol agent

Add these to your workspace TOOLS.md (or equivalent config):

### ClawTrol (Task Dashboard / Mission Control)
| Key | Value |
|-----|-------|
| URL | http://HOST:PORT |
| API Token | API_TOKEN |
| Hooks Token | HOOKS_TOKEN |
| Agent Name | YOUR_AGENT_NAME |
| Agent Emoji | YOUR_EMOJI |

Add these env vars (e.g., ~/.openclaw/.env or your agent's env):

CLAWTROL_API_TOKEN=API_TOKEN
CLAWTROL_HOOKS_TOKEN=HOOKS_TOKEN

APP_BASE_URL=http://HOST:PORT # Used for webhook callbacks and links

**Step 7 — Set up heartbeat polling**

Add to your HEARTBEAT.md (or equivalent periodic check):
```markdown
### ClawTrol Tasks
# Health check first
curl -sf http://HOST:PORT/up >/dev/null 2>&1 || echo "⚠️ ClawTrol DOWN"

# Poll for assigned tasks
source ~/.openclaw/.env  # or wherever your env is
curl -s -H "Authorization: Bearer $CLAWTROL_API_TOKEN" \
  http://HOST:PORT/api/v1/tasks?assigned=true&status=up_next

Step 8 — Set up the completion contract

After EVERY task you complete, fire these two hooks IN ORDER:

Hook 1 — task_outcome (structured result):

curl -s -X POST http://HOST:PORT/api/v1/hooks/task_outcome \
  -H "X-Hook-Token: $CLAWTROL_HOOKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1",
    "task_id": TASK_ID,
    "run_id": "SESSION_UUID",
    "ended_at": "ISO8601_TIMESTAMP",
    "needs_follow_up": false,
    "recommended_action": "in_review",
    "summary": "What was accomplished",
    "achieved": ["item 1", "item 2"],
    "evidence": ["proof 1"],
    "remaining": []
  }'

Hook 2 — agent_complete (saves output + transitions status):

curl -s -X POST http://HOST:PORT/api/v1/hooks/agent_complete \
  -H "X-Hook-Token: $CLAWTROL_HOOKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": TASK_ID,
    "session_id": "SESSION_UUID",
    "findings": "Detailed summary of work done",
    "output_files": ["file1.rb", "file2.js"]
  }'

Step 9 — Verify the full loop

Create a test task, execute it, fire both hooks, confirm it reaches done (or in_review):

# Create
TASK=$(curl -s -X POST http://HOST:PORT/api/v1/tasks \
  -H "Authorization: Bearer $CLAWTROL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Test: onboarding verification","board_id":BOARD_ID,"status":"up_next","tags":["test","quick-fix"],"assigned_to_agent":true}')
TASK_ID=$(echo $TASK | jq -r .id)

# Move to in_progress
curl -s -X PATCH http://HOST:PORT/api/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $CLAWTROL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_progress"}'

# Fire hooks (use a random UUID as run_id)
# ... (fire task_outcome + agent_complete as above)

# Verify final status
curl -s -H "Authorization: Bearer $CLAWTROL_API_TOKEN" \
  http://HOST:PORT/api/v1/tasks/$TASK_ID | jq .status
# Should be "done" (auto-review: quick-fix + output) or "in_review"

Step 10 — Report to me

Tell me:

• ✅ Dashboard URL
• ✅ Board created
• ✅ API + Hooks tokens saved
• ✅ Heartbeat configured
• ✅ Completion hooks tested
• ✅ Test task verified end-to-end

---

Replace before pasting:

Placeholder	Description
MY_EMAIL	Your login email
MY_PASSWORD	Secure password (12+ chars)
MY_NAME	Display name
HOST:PORT	Your server address (e.g., localhost:4001)
YOUR_AGENT_NAME	What your agent calls itself
YOUR_EMOJI	Agent's signature emoji
BOARD_ID	Board ID from Step 5 (usually 1)

Requirements:

• Docker (recommended) or Ruby 3.3+ with PostgreSQL
• AI assistant with shell/exec access (OpenClaw, Claude Code, Codex CLI, etc.)
• 5 minutes

---

API

ClawTrol exposes a REST API for agent integrations. Get your API token from Settings.

Authentication

Include your token in every request:

Authorization: Bearer YOUR_TOKEN

Include agent identity headers:

X-Agent-Name: Otacon
X-Agent-Emoji: 📟

---

Boards

# List boards
GET /api/v1/boards

# Get board
GET /api/v1/boards/:id

# Create board
POST /api/v1/boards
{ "name": "My Project", "icon": "🚀" }

# Update board
PATCH /api/v1/boards/:id

# Delete board
DELETE /api/v1/boards/:id

---

Tasks

Standard CRUD

# List tasks (with filters)
GET /api/v1/tasks
GET /api/v1/tasks?board_id=1
GET /api/v1/tasks?status=in_progress
GET /api/v1/tasks?assigned=true    # Your work queue

# Get task
GET /api/v1/tasks/:id

# Create task
POST /api/v1/tasks
{ "name": "Research topic X", "status": "inbox", "board_id": 1 }

# Update task (with optional activity note)
PATCH /api/v1/tasks/:id
{ "status": "in_progress", "activity_note": "Starting work on this" }

# Delete task
DELETE /api/v1/tasks/:id

# Complete task
PATCH /api/v1/tasks/:id/complete

# Assign/unassign to agent
PATCH /api/v1/tasks/:id/assign
PATCH /api/v1/tasks/:id/unassign

Agent-Specific Endpoints

# Create task ready for agent (auto-routes to board based on name)
POST /api/v1/tasks/spawn_ready
{ "name": "ProjectName: Task title", "description": "...", "model": "opus" }

# Link agent session to task
POST /api/v1/tasks/:id/link_session
{ "agent_session_id": "uuid", "agent_session_key": "key" }

# Save agent output and complete (legacy/manual path)
POST /api/v1/tasks/:id/agent_complete
{ "output": "Task completed successfully", "status": "in_review" }

# Recover missing output from transcript (.jsonl)
POST /api/v1/tasks/:id/recover_output

# Get live agent activity log
GET /api/v1/tasks/:id/agent_log

# Check session health
GET /api/v1/tasks/:id/session_health

Follow-up Tasks

# Generate AI-suggested follow-up
POST /api/v1/tasks/:id/generate_followup

# Create follow-up task
POST /api/v1/tasks/:id/create_followup
{ "name": "Follow-up task name", "description": "..." }

---

Webhook: Agent Complete (Auto-Save Pipeline)

POST /api/v1/hooks/agent_complete

Primary endpoint for autonomous agents to self-report completion and persist output. This is the recommended integration path for production agents.

Authentication

Send webhook token in header:

X-Hook-Token: YOUR_HOOKS_TOKEN

Request Body (JSON)

Field	Type	Required	Description
task_id	integer	✅	Target task ID to update
findings	string	✅	Work summary; stored under ## Agent Output
session_id	string	optional	Agent session UUID for transcript/activity linking
session_key	string	optional	Session key used by terminal/transcript viewer
output_files	array[string]	optional	Explicit output file list (merged with auto-extracted files)

Example Request

curl -s -X POST http://YOUR_HOST:4001/api/v1/hooks/agent_complete \
  -H "X-Hook-Token: YOUR_HOOKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": 302,
    "findings": "Implemented feature X and updated docs.",
    "session_id": "sess_123",
    "session_key": "agent:main:subagent:abc",
    "output_files": ["README.md", "app/controllers/tasks_controller.rb"]
  }'

Behavior

• Auto-appends/updates ## Agent Output in task description
• Auto-transitions task status to in_review
• Links session metadata when provided
• Auto-extracts output files from findings text and transcript commit data
• Merges + deduplicates discovered files and provided output_files

Success Response

• 200 OK with updated task payload

Error Responses

• 401 Unauthorized — missing/invalid X-Hook-Token
• 404 Not Found — task not found
• 422 Unprocessable Entity — invalid payload (e.g., missing required fields)

Models (Rate Limiting)

# Get all models status
GET /api/v1/models/status

# Get best available model
POST /api/v1/models/best
{ "preferred": "opus" }

# Record rate limit for a model
POST /api/v1/models/:name/limit
{ "duration_minutes": 60 }

---

Nightshift

# List tonight's mission selections
GET /api/v1/nightshift/selections

# Update mission status (for agents reporting back)
PATCH /api/v1/nightshift/selections/:id
{ "status": "completed", "result": "All checks passed" }

# List all available missions
GET /api/v1/nightshift/tasks

# Launch selected missions
POST /api/v1/nightshift/launch
{ "task_ids": [1, 3, 5] }

Saved Links

# List saved links
GET /api/v1/saved_links

# Create saved link
POST /api/v1/saved_links
{ "url": "https://github.com/example/repo", "title": "Example Repo" }

# Update saved link
PATCH /api/v1/saved_links/:id

# Get pending links
GET /api/v1/saved_links/pending

Swarm Ideas

# List swarm ideas
GET /api/v1/swarm_ideas

# Create swarm idea
POST /api/v1/swarm_ideas
{ "swarm_idea": { "title": "Fix auth bugs", "description": "...", "category": "bug-fix", "suggested_model": "codex" } }

# Update swarm idea
PATCH /api/v1/swarm_ideas/:id

# Delete swarm idea
DELETE /api/v1/swarm_ideas/:id

# Launch idea as task
POST /api/v1/swarm_ideas/:id/launch
{ "board_id": 1, "model": "codex" }

Pipeline

# Pipeline status overview
GET /api/v1/pipeline/status

# Enable pipeline on a board
POST /api/v1/pipeline/enable_board/:board_id

# Disable pipeline on a board
POST /api/v1/pipeline/disable_board/:board_id

# Get pipeline log for a task
GET /api/v1/pipeline/task/:id/log

# Reprocess a task through the pipeline
POST /api/v1/pipeline/reprocess/:id

# Route a specific task through pipeline
POST /api/v1/tasks/:id/route_pipeline

# Get pipeline info for a task
GET /api/v1/tasks/:id/pipeline_info

Agent Personas

# List agent personas
GET /api/v1/agent_personas

# Create persona
POST /api/v1/agent_personas
{ "name": "Security Bot", "board_id": 1, "model": "codex" }

# Import personas
POST /api/v1/agent_personas/import

# Update persona
PATCH /api/v1/agent_personas/:id

# Delete persona
DELETE /api/v1/agent_personas/:id

Factory Loops

# List factory loops
GET /api/v1/factory/loops

# Create factory loop
POST /api/v1/factory/loops
{ "name": "Nightly bugs", "board_id": 1 }

# Control loop
POST /api/v1/factory/loops/:id/play
POST /api/v1/factory/loops/:id/pause
POST /api/v1/factory/loops/:id/stop

# Loop metrics
GET /api/v1/factory/loops/:id/metrics

# Complete a factory cycle
POST /api/v1/factory/cycles/:id/complete

Recurring Tasks

# List recurring task templates
GET /api/v1/tasks/recurring

---

Task Statuses

Status	Description
inbox	New, not prioritized
up_next	Ready to be assigned
in_progress	Being worked on
in_review	Done, needs human review
done	Complete

Pipeline Stages

unstarted, triaged, context_ready, routed, executing, verifying, completed, failed

Priorities

none, low, medium, high

Models

opus, codex, gemini, glm, sonnet, flash

---

UI Features

Terminal Panel

• Tabbed Interface — Multiple agent sessions in tabs
• Hover Preview — Quick preview on card hover
• Pin to Terminal — Lock a task's output in view
• Live Streaming — Real-time agent activity via WebSocket
• Session Transcript — Full conversation log with role icons and tool calls

Kanban Board

• WebSocket Updates — Real-time via ActionCable (polling fallback)
• Spinner Indicator — Shows active agent on card
• Context Menu — Right-click to move between boards/statuses
• Board Tabs — Quick navigation between projects
• Drag & Drop — SortableJS with delete drop zone
• Dependency Blocking — 🔒 badge prevents moving blocked tasks

Task Modal

• Two-Column Layout — Details left, agent activity + files right (desktop)
• Auto-Save — Debounced 500ms save on field changes
• File Viewer — Browse output files with syntax highlighting + fullscreen
• Agent Activity — Live session log with WebSocket updates
• Priority Selector — Visual fire icon buttons
• Validation Output — View command results inline

---

Commit Convention

This project uses Conventional Commits. A git hook validates your commit messages automatically.

Format: <type>[optional scope]: <description>

Types: feat, fix, docs, chore, refactor, test, ci, style, perf, build

Setup the hook:

ln -sf ../../bin/commit-msg-hook .git/hooks/commit-msg

Generate changelog:

bin/changelog

The changelog is also auto-generated on pushes to main via GitHub Actions.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.

Links

• 🐙 GitHub: wolverin0/clawtrol
• 🦞 Upstream: clawdeckio/clawdeck

Telegram Notification Routing (Strict Origin)

ClawTrol stores routing metadata on each task and always routes completion output to the task origin.

• origin_chat_id (string) — Telegram chat/group ID where the task originated
• origin_thread_id (integer) — Telegram topic/thread ID where the task originated
• origin_session_key (string, optional) — OpenClaw session for direct session-delivery

Behavior

1. Task created from a Telegram topic → output is sent back to that same topic.
2. Task created from chat root (no topic) → output is sent to chat root.
3. No origin_chat_id → Telegram delivery is skipped (no fallback to default chat/topic).
4. There is no default-thread fallback in strict mode.

Setup

1. Set CLAWTROL_TELEGRAM_BOT_TOKEN env var with your Telegram bot token.
2. Ensure task creation always includes origin_chat_id and, for forum topics, origin_thread_id.

curl -X POST http://localhost:4001/api/v1/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task": {"name": "Fix bug", "origin_chat_id": "-100123456789", "origin_thread_id": 42}}'

3. On in_review / done, completion notification is delivered to the stored origin.
4. Webhook notifications (webhook_notification_url) still work as a secondary mechanism.

---

Built with 🦞 by the OpenClaw community.