Contributing to OpenClaw Dashboard

August 14, 2026 · View on GitHub

Thanks for your interest in contributing! 🦞

OpenClaw Dashboard is built to be simple, fast, and useful for personal AI agent observability. Contributions that align with these principles are always welcome.

🚀 Quick Start (Development)

1. Clone & Setup

git clone https://github.com/vivekchand/clawmetry.git
cd clawmetry
pip install -r requirements.txt

2. Run Locally

python3 dashboard.py --port 8900
# Opens at http://localhost:8900

3. Test Console Entry Point

pip install -e .
clawmetry --help

4. Make Changes & Test

  • Edit the relevant Blueprint in routes/ (or dashboard.py for shared helpers / embedded templates — see CLAUDE.md for the file map)
  • Restart dashboard to see changes
  • Test auto-detection: cd /tmp && python3 /path/to/dashboard.py

📁 Project Structure

clawmetry/
├── dashboard.py          # 🎯 Flask app, blueprint registration, shared helpers
├── routes/               # 🧩 Per-feature Blueprints (sessions, channels, brain, usage, health, …)
├── clawmetry/            # 📦 Installable package — CLI, sync daemon, proxy, interceptor, providers
├── history.py            # 📈 Optional time-series collector (SQLite)
├── README.md             # 📖 Documentation
├── setup.py              # 📦 Package configuration
├── requirements.txt      # 🔧 Dependencies
├── screenshots/          # 🖼️  UI screenshots
├── LICENSE               # ⚖️  MIT license
└── CONTRIBUTING.md       # 📝 This file

See CLAUDE.md (Key Files) for the full per-module breakdown including line counts and Blueprint names.

Philosophy: Keep it simple. The dashboard core is a Flask app in dashboard.py (shared helpers + blueprint registration; live frontend is in clawmetry/static/ + clawmetry/templates/) and a small routes/ package of feature Blueprints — minimal dependencies, easy to understand, modify, and deploy.

🎯 Contribution Guidelines

What We're Looking For

  • 🐛 Bug fixes - especially around auto-detection, log parsing, or UI edge cases
  • ✨ Small features - new visualizations, better error handling, performance improvements
  • 📖 Documentation - clearer setup instructions, troubleshooting guides
  • 🎨 UI polish - better mobile support, dark theme, accessibility improvements
  • 🧪 Testing - help us test on different OpenClaw setups

What to Avoid

  • ❌ Complex dependencies - no heavy frameworks, ML libraries, or databases
  • ❌ Sprawling new top-level modules - prefer adding to an existing routes/ Blueprint, or extending dashboard.py's shared helpers, before introducing a new package
  • ❌ Enterprise features - this is for personal AI agents, not teams
  • ❌ Major architectural changes - discuss large changes in Issues first

🛠️ Development Guidelines

Code Style

  • Python 3.8+ compatible
  • PEP 8 formatting (but don't obsess)
  • Clear variable names - readability over brevity
  • Comments for complex logic - especially auto-detection and log parsing
  • No external formatting tools required - just make it readable

Testing Your Changes

Before submitting, test these scenarios:

  1. Auto-detection works:

    cd /tmp
python3 /path/to/dashboard.py --port 9999
# Should find your OpenClaw workspace automatically

  2. CLI arguments work:

    python3 dashboard.py --help
python3 dashboard.py --workspace ~/myagent --port 8901

  3. Console entry point works (after pip install -e .):

    clawmetry --version
clawmetry --port 8902

  4. UI loads without errors:

    • Visit all tabs (Overview, Usage, Sessions, etc.)
    • Check browser console for JS errors
    • Test with/without OpenClaw running

MOAT tests that add or change synthetic event_type shapes must also update tests/MOAT_EVENT_SHAPES.md. Each synthetic shape needs a live-fixture sibling listed in the manifest so real OpenClaw event-shape drift is covered.

Adding New Features

If you want to add a new tab or major feature:

  1. Open an Issue first - describe what you want to build and why
  2. Keep it lightweight - minimal dependencies, no heavy frameworks
  3. Follow the existing pattern - look at how other tabs are implemented
  4. Update the README - document your new feature in the features table

📝 Pull Request Process

Before You Submit

  • Test auto-detection from different directories
  • Verify console entry point still works
  • Check that all tabs load without errors
  • Run dashboard with real OpenClaw logs
  • Update README if you added features

PR Description Template

## What This PR Does
Brief description of the change.

## Testing
- [ ] Tested auto-detection: `cd /tmp && python3 dashboard.py`
- [ ] Tested console entry point: `clawmetry --help`
- [ ] Tested new feature with real OpenClaw data
- [ ] All tabs load without browser console errors

## Screenshots (if UI changes)
![Before/After or Demo GIF]

Review Process

  • PRs are usually reviewed within 48 hours
  • Small fixes may be merged quickly
  • New features will get more thorough review
  • We may ask for changes to keep things simple

🐛 Bug Reports

Good Bug Report Template

**What happened?**
Brief description.

**Steps to reproduce:**
1. Start dashboard with `clawmetry`
2. Click on Sessions tab
3. Error appears in browser console

**Environment:**
- OS: Linux/macOS/Windows
- Python version: `python3 --version` 
- OpenClaw version: X.X.X
- Dashboard version: `clawmetry --version`

**Logs/Screenshots:**
Paste relevant error messages or attach screenshots.

Where to Find Logs

  • Dashboard errors: Check terminal where you ran dashboard.py
  • Browser errors: Check browser Developer Tools → Console
  • OpenClaw logs: Usually in /tmp/moltbot/ or /tmp/openclaw/

💡 Feature Requests

Have an idea? Great! But first:

  1. Check existing Issues - someone might have already suggested it
  2. Consider the scope - would this benefit most personal AI agent users?
  3. Think about complexity - can it be done without adding dependencies?

Good Feature Request Template

**Problem:**
What pain point does this solve?

**Proposed Solution:**
Brief description of what you want.

**Alternatives:**
Other ways this could be solved.

**Use Case:**
How would you personally use this feature?

📞 Questions?

  • General questions: Open a GitHub Discussion
  • Bug reports: Open a GitHub Issue
  • Feature requests: Open a GitHub Issue
  • Quick questions: Find @vivekchand on Twitter/LinkedIn

🏆 Recognition

Contributors who help improve OpenClaw Dashboard will be:

  • Added to a CONTRIBUTORS section in the README
  • Mentioned in release notes for significant contributions
  • Given credit in any blog posts or talks about the project

🧪 Cloud Testing

For testing against real cloud deployments or verifying ClawMetry Cloud integrations, see docs/CLOUD_TESTING.md.

📄 License

By contributing to OpenClaw Dashboard, you agree that your contributions will be licensed under the same MIT License that covers the project.

Thanks for making OpenClaw Dashboard better! 🦞