Tools
Clawboard
By ๐ AI Dashboard for OpenClaw โ task board, project management, session browser, real-time agent monitoring, and plugin system. Docker-ready.
Configuration Example
volumes:
- ${OPENCLAW_WORKSPACE:-~/.openclaw/workspace}:/workspace:roREADME
# ๐ ClawBoard
**Your AI Dashboard for OpenClaw**
ClawBoard is a comprehensive web-based dashboard for managing and monitoring your OpenClaw AI agent. It provides a beautiful, modern interface for task management, project tracking, journal entries, conversation history, and real-time agent monitoring.
[](LICENSE)
[](docker-compose.prod.yml)
[](https://www.postgresql.org/)
> ****Repository:** [github.com/Wadera/clawboard](https://github.com/Wadera/clawboard)
## โจ Features
- **๐ Task Board** โ Kanban-style task management with drag-and-drop, subtasks, priorities, and dependencies
- **๐๏ธ Project Management** โ Organize tasks into projects with links, notebooks, environments, and resources
- **๐ Journal** โ Daily journal entries with mood tracking, multi-entry per day, and navigation
- **๐ฌ Sessions** โ Browse and search through all agent conversation transcripts
- **๐ค Real-time Agent Status** โ Monitor your OpenClaw agent's activity, connections, and health
- **๐ Statistics** โ Visual insights into task completion, project progress, and agent activity
- **๐ Plugin System** โ Extend your dashboard with Docker-based plugins (journals, monitors, blogs, etc.)
- **๐จ Fully Customizable** โ Theme colors, branding, feature toggles, custom avatars
- **๐ Secure** โ Password-protected with JWT authentication
- **๐ณ Docker-Ready** โ Complete Docker Compose setup with health checks
- **๐ Real-time Updates** โ WebSocket integration for live dashboard updates
## ๐ผ๏ธ Screenshots
### Dashboard
### Tasks
### Projects
### Sessions
### Journal
### Stats & Tools
### Audit
### GPU Gateway Plugin
## ๐ Quick Start
Get ClawBoard running in **5 minutes**:
```bash
# 1. Clone repository
git clone https://github.com/Wadera/clawboard.git
cd ClawBoard
# 2. Run setup script (generates .env with password hash)
./setup.sh
# 3. Start services
docker compose up -d
# 4. Access dashboard
open http://localhost:8080/dashboard/
```
**Prerequisites:**
- Docker & Docker Compose
- OpenClaw installed and running
- 2GB RAM, 1 CPU core
**What the setup script does:**
- Creates `.env` from `.env.example`
- Generates bcrypt password hash for dashboard login
- Sets up database credentials and JWT secret
- Configures OpenClaw integration paths
- Creates data and backup directories
## ๐ง OpenClaw Workspace Integration
ClawBoard automatically reads and displays your bot's workspace files, giving you direct visibility into your agent's personality, memory, and configuration.
### What Gets Loaded
The following files from your OpenClaw workspace are accessible in the dashboard:
- **SOUL.md** โ Your bot's personality, identity, and core values
- **HEARTBEAT.md** โ Heartbeat monitoring configuration and tasks
- **AGENTS.md** โ Agent behavior, memory rules, and conventions
- **USER.md** โ Information about the human the bot serves
- **memory/YYYY-MM-DD.md** โ Daily memory logs
- **memory/*.md** โ Additional memory files
### How It Works
The workspace is mounted **read-only** into the ClawBoard backend container:
```yaml
volumes:
- ${OPENCLAW_WORKSPACE:-~/.openclaw/workspace}:/workspace:ro
```
Configuration in `.env`:
```bash
# Path to your bot's workspace directory
OPENCLAW_WORKSPACE=~/.openclaw/workspace
```
### Dashboard Features
When workspace files are loaded, you'll see:
- **Workspace Files Widget** โ Browse and view workspace files directly in the dashboard
- **Bot Personality Card** โ Displays bot name and identity from SOUL.md
- **Memory Timeline** โ Navigate through daily memory logs
- **Quick File Access** โ Jump to any workspace file with one click
### Verification
To verify the workspace integration is working:
1. Log into the dashboard at `http://localhost:8080/dashboard/`
2. Look for the "Workspace Files" widget on the main dashboard
3. Click on any file (e.g., SOUL.md) to view its contents
4. If files don't appear, check:
- `.env` has correct `OPENCLAW_WORKSPACE` path
- The path exists and contains the expected files
- Docker container has been restarted after .env changes
### Troubleshooting
**Files not showing up?**
```bash
# Check if workspace path is correct
ls -la ~/.openclaw/workspace
# Verify .env configuration
grep OPENCLAW_WORKSPACE .env
# Restart containers to pick up changes
docker compose restart clawboard-backend
```
**Permission issues?**
The workspace is mounted read-only, so ClawBoard cannot modify your files. If you need to edit them, use your preferred editor on the host system.
## ๐ Heartbeat Watchdog
ClawBoard includes **clawbeat** โ a proactive monitoring tool that checks task status, agent activity, and orchestration needs.
### What It Does
Clawbeat runs periodically (e.g., every 15 minutes) to:
1. **Check Active Sub-agents** โ Avoids interrupting ongoing work
2. **Monitor Stuck Tasks** โ Detects tasks awaiting subtask review with retry tracking
3. **Track In-Progress Tasks** โ Identifies stalled or crashed processes
4. **Auto-Start Ready Tasks** โ Generates spawn-ready prompts for tasks marked `autoStart=true`
### Configuration
Set up environment variables or config file:
```bash
# Environment variables
export CLAWBOARD_API_URL="http://localhost:3001/api"
export CLAWBOARD_TOKEN="your-api-token"
# Or use config file
mkdir -p ~/.config/clawboard
echo '{"api_token": "your-token"}' > ~/.config/clawboard/config.json
```
### Usage
```bash
# Normal run (outputs JSON)
python3 cli/clawbeat.py
# Debug mode
python3 cli/clawbeat.py --verbose
# Dry run (no side effects)
python3 cli/clawbeat.py --dry-run
# Override API URL
python3 cli/clawbeat.py --api http://custom-host:3001/api
```
### Example Output
```json
{"action": "HEARTBEAT_OK", "reason": "All systems nominal"}
{"action": "WAKE",
"message": "ORCHESTRATE: Stuck Task [abc123] Needs Review\n...",
"reason": "Task abc123 stuck โ needs subtask review",
"task_id": "abc123",
"attempt": 1,
"recommended_action": "review"}
```
### Integration with HEARTBEAT.md
Run via cron or OpenClaw heartbeat polling:
**Option 1: Cron (runs every 15 minutes)**
```bash
*/15 * * * * cd /path/to/clawboard && python3 cli/clawbeat.py
```
**Option 2: HEARTBEAT.md in OpenClaw workspace**
```markdown
# HEARTBEAT.md
Every heartbeat (15 min interval):
1. Check clawbeat status
2. If WAKE action, follow orchestration instructions
3. Log actions to /tmp/orchestration-actions.log
Command:
```bash
cd /path/to/clawboard && python3 cli/clawbeat.py
```
```
### Features
- **Context-Rich Prompts** โ Full task details, subtasks, project context
- **Retry Tracking** โ Escalates after 3 failed attempts (`/tmp/clawbeat-retries.json`)
- **Deduplication** โ Won't re-wake for same task within 30 minutes (`/tmp/orchestration-actions.log`)
- **Process Monitoring** โ Checks external process health via `/tmp/task-*-status.json`
- **Zero Dependencies** โ Python 3 stdlib only (requests optional)
### How It Works
1. **Active Sub-agent Check** โ Scans `~/.openclaw/agents/main/sessions/` for recently active subagent sessions
2. **API Queries** โ Fetches tasks via ClawBoard API (`/api/tasks?status=stuck`, etc.)
3. **Context Gathering** โ Uses `clawboard` CLI to get full task details, subtasks, and project info
4. **Decision Tree** โ Outputs `HEARTBEAT_OK` if all clear, or `WAKE` with detailed orchestration instructions
### Retry Escalation
Tasks are retried automatically with escalation:
- **Attempt 1-2:** Normal retry with context
- **Attempt 3+:** Escalation warning โ approach may be wrong, consider human review
### Recommended Actions
The `recommended_action` field guides the orchestrator:
- `review` โ Check subtasks and approve/reject
- `spawn_agent` โ Ready to spawn agent for new task
- `restart_process` โ External process crashed, needs restart
- `escalate` โ 3+ failures, needs human intervention
See the [heartbeat-monitoring tool](database/init.sql) for full details.
## ๐ Documentation
Documentation lives in [`docs/`](docs/):
- **[Getting Started](docs/getting-started.md)** โ 5-minute quick start guide
- **[Plugin Development](docs/plugin-development.md)** โ Build your own plugins
- **[Example Plugin](docs/example-plugin/)** โ Minimal hello-world plugin to learn from
- **[Project Overview](docs/PROJECT-OVERVIEW.md)** โ Architecture deep dive
- **[Deployment Guide](DEPLOYMENT.md)** โ Production deployment (Traefik, Nginx, Docker)
- **[Database Guide](database/README.md)** โ Schema, backup, restore
- **[Contributing](CONTRIBUTING.md)** โ How to contribute
## ๐๏ธ Architecture
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ClawBoard Frontend โ
โ React + TypeScript + Vite โ
โ Port: 8080 โ 80 โ
โโโโโโโโโโโโโโฌโโโโโโโโโโโ
... (truncated)
tools
Comments
Sign in to leave a comment