"The Overmind speaks through many voices, but with one purpose."
Welcome, AI agent. This document defines how you should interact with this codebase.
All changes to this repository MUST go through pull requests.
This is a public open source project. Even maintainers (including AI agents working on behalf of maintainers) must:
- Create a feature branch (
git checkout -b type/description) - Make changes and commit
- Push branch and open a PR
- Get approval before merging
Never push directly to main. This applies to everyone, including the repo owner.
OpenClaw Command Center is the central dashboard for AI assistant management. Your mission is to help build, maintain, and improve this system while maintaining the Starcraft/Zerg thematic elements that make it unique.
Read First: docs/architecture/OVERVIEW.md
Key architectural principles:
- DRY β Don't Repeat Yourself. Extract shared code to partials/modules.
- Zero Build Step β Plain HTML/CSS/JS, no compilation needed.
- Real-Time First β SSE for live updates, polling as fallback.
- Progressive Enhancement β Works without JS, enhanced with JS.
openclaw-command-center/
βββ lib/ # Core server logic
β βββ server.js # Main HTTP server and API routes
β βββ config.js # Configuration loader with auto-detection
β βββ jobs.js # Jobs/scheduler API integration
β βββ linear-sync.js # Linear issue tracker integration
β βββ topic-classifier.js # NLP-based topic classification
βββ public/ # Frontend assets
β βββ index.html # Main dashboard UI
β βββ jobs.html # AI Jobs management UI
β βββ partials/ # β Shared HTML partials (DRY!)
β β βββ sidebar.html # Navigation sidebar component
β βββ css/
β β βββ dashboard.css # Shared styles
β βββ js/
β βββ sidebar.js # Sidebar loader + SSE badges
β βββ app.js # Main dashboard logic
β βββ lib/ # Third-party libraries
βββ scripts/ # Operational scripts
βββ config/ # Configuration (be careful!)
βββ docs/ # Documentation
β βββ architecture/ # Architecture Decision Records
βββ tests/ # Test files
βββ SKILL.md # ClawHub skill metadata
βββ package.json # Version and dependencies
Do freely:
- Read any file to understand the codebase
- Create/modify files in
lib/,public/,docs/,tests/ - Add tests
- Update documentation
- Create feature branches
Check with a human before:
- Modifying
config/files - Changing CI/CD workflows
- Adding new dependencies to
package.json - Making breaking API changes
- Anything touching authentication/secrets
- Push directly to
mainbranch β ALL changes require PRs - Commit secrets, API keys, or credentials
- Commit user-specific data files (see
public/data/AGENTS.md) - Delete files without confirmation
- Expose internal endpoints publicly
# Install pre-commit hooks (required for all contributors)
make install-hooks
# Or manually:
cp scripts/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commitThe pre-commit hook enforces rules from this file automatically.
# Create feature branch
git checkout -b feat/your-feature-name
# Make changes, then test locally
npm test
npm run lint
make check # Run pre-commit checks manually
# Commit with descriptive message
git commit -m "feat: add overlord status indicator"
# Push and create PR
git push -u origin feat/your-feature-nameFollow Conventional Commits:
feat:β New featurefix:β Bug fixdocs:β Documentation onlystyle:β Formatting, no code changerefactor:β Code restructuringtest:β Adding testschore:β Maintenance tasks
- Use ESLint configuration provided
- Prettier for formatting
- JSDoc comments for public functions
- Meaningful variable names (thematic names encouraged!)
UI fixes and refactors must preserve data-i18n and related localization hooks. If wording changes meaning, replace the key deliberately and update every supported locale; do not remove localization to make dynamic rendering easier. Keep translated labels separate from runtime values so updates cannot overwrite their hooks. Localize new loading, error, tooltip, and dynamic text through the existing i18n mechanisms. Verify English β Chinese β English switching with the affected panel open and after live updates, and retain regression coverage for the hooks.
This project is distributed as a ClawHub skill. After changes are merged to main, they need to be published to the registry so users can install/update via clawhub install command-center.
Two files control the skill identity:
SKILL.mdβ Frontmatter (name,version,description) used by ClawHub for discovery and searchpackage.jsonβversionfield for npm compatibility
Both package.json and SKILL.md MUST have the same version number. This is enforced by pre-commit hooks.
# If you change version in one file, change it in both:
# package.json: "version": "1.0.4"
# SKILL.md: version: 1.0.4The pre-commit hook will block commits if versions are out of sync.
# 1. Authenticate (one-time)
clawhub login
clawhub whoami
# 2. Bump version in package.json (follow semver)
# patch: bug fixes (0.1.0 β 0.1.1)
# minor: new features (0.1.0 β 0.2.0)
# major: breaking changes (0.1.0 β 1.0.0)
# 3. Tag the release
git tag -a v<new-version> -m "v<new-version> β short description"
git push origin --tags
# 4. Publish
clawhub publish . --slug command-center --version <new-version> \
--changelog "Description of what changed"
# Or use the release script (handles tagging + publishing):
./scripts/release.sh <new-version># Check published metadata
clawhub inspect command-center
# Test install into a workspace
clawhub install command-center --workdir /path/to/workspaceUsers update with:
clawhub update command-centerThe installed version is tracked in .clawhub/origin.json within the skill directory.
Only maintainers with ClawHub credentials for jontsai/command-center can publish. Currently:
- @jontsai (owner)
Contributors: Submit PRs. After merge, a maintainer will handle the ClawHub publish.
Before publishing a new version:
- All PRs for the release are merged to
main - Version bumped in both
package.jsonandSKILL.mdfrontmatter - CHANGELOG updated (if maintained)
- Tests pass:
npm test - Lint passes:
npm run lint - Git tag created:
git tag -a v<version> -m "v<version>" - Tag pushed:
git push origin --tags - Published to ClawHub with changelog
This project has a Starcraft/Zerg theme. When naming things:
| Concept | Thematic Name |
|---|---|
| Main controller | Overmind |
| Worker processes | Drones |
| Monitoring service | Overlord |
| Cache layer | Creep |
| Message queue | Spawning Pool |
| Health check | Essence scan |
| Error state | Corrupted |
Example:
// Instead of: const cacheService = new Cache();
const creepLayer = new CreepCache();
// Instead of: function checkHealth()
function scanEssence()When you add features, document them:
- Code comments β JSDoc for functions
- README updates β If user-facing
- API docs β In
docs/api/for endpoints - Architecture Decision Records β In
docs/architecture/for major changes
# Run all tests
npm test
# Coverage report
npm run test:coverageAim for meaningful test coverage. Test the logic, not the framework.
# Enable all command-center debug output
DEBUG=openclaw:* npm run dev
# Specific namespaces
DEBUG=openclaw:api npm run dev
DEBUG=openclaw:overlord npm run devWhen handing off to another AI or ending a session:
- Commit all work in progress
- Document current state in a comment or commit message
- List any unfinished tasks
- Note any decisions that need human input
Problem: Sidebar was duplicated across index.html and jobs.html, causing inconsistencies.
Solution: Extract to /partials/sidebar.html + /js/sidebar.js for loading.
Lesson: When you see similar code in multiple places, stop and extract it. The cost of extraction is always lower than maintaining duplicates.
Problem: "Scheduled Jobs" vs "Cron Jobs" vs "Jobs" caused confusion. Solution: Established naming convention: "Cron Jobs" for OpenClaw scheduled tasks, "AI Jobs" for advanced agent jobs. Lesson: Agree on terminology early. Document it. Enforce it.
Context: No build step keeps things simple but limits some patterns.
Solution: Use fetch() to load partials dynamically, <script> for shared JS.
Lesson: This works well for dashboards. Evaluate trade-offs for your use case.
Problem: Multiple components each opening SSE connections.
Solution: Single SSE connection in sidebar.js, shared state management.
Lesson: Centralize real-time connections. Components subscribe to state, not sources.
Problem: Easy to break things when refactoring HTML structure.
Solution: make restart + browser check after each change.
Lesson: Keep feedback loops tight. Visual changes need visual verification.
Problem: Future agents (or humans) don't know why things are the way they are.
Solution: Create docs/architecture/OVERVIEW.md and ADRs.
Lesson: Write down the "why", not just the "what".
- SKILL.md β ClawHub skill metadata
- CONTRIBUTING.md β Contribution guidelines
- docs/ β Detailed documentation
"Awaken, my child, and embrace the glory that is your birthright."
Command Center owns generic OpenClaw monitoring and extension-host infrastructure. Spacesuit owns optional per-agent flavors and domain extensions. Do not add new agent-specific business rules, workspace file conventions or panels to Command Center core. Keep public flavor packages generic and private bindings in the workspace. Preserve localization, profile isolation and core-only operation.
Read the core/flavor boundary before adding panels or collectors.
The first read-only host is implemented in src/extensions.js; see
extension API v1. Preserve explicit core-only
operation, legacy compatibility, independent snapshot failures and locale hooks.
Command Center must work standalone; Spacesuit is highly recommended but has no
humanβagent graphical interaction surface without Command Center. Do not describe
workspace scaffolding as an independent dashboard or promise a chat composer.
Preserve data-i18n hooks and existing translations in UI changes. Localize new
static and dynamic labels in English and Chinese, including unavailable/error
states. Keep raw business data separate from localized labels; never infer its
translation. Verify language switching while new panels are open.
Read the project portfolio contract before changing board or adapter behavior. Tracker-specific APIs, entity/status mappings, memory conventions and retrieval strategies belong in Spacesuit adapters. Core owns provider-independent presentation and bounded snapshot validation. Keep projects, tasks and runtime sessions distinct. Never infer cross-source identity by title or convert missing metrics/statuses to zero/Done. Preserve source-native states and explicit capabilities; no external writes or live tracker credentials in UI code.