Project Dashboard User Guide

A complete walkthrough of the OpenClaw Project Dashboard interface, workflows, and best practices.

Overview
Views
Task Operations
Filtering & Search
Archive Workflow
One-Click Actions & Confirmations
Ask Bar (NL Commands)
Budget Management
Install as a Desktop App (PWA)
Keyboard Shortcuts
Appearance: Themes & Accent Packs
Agent Integration
Import / Export
Accessibility

Overview

The dashboard is a single‑page application served at http://localhost:3876/. It connects to a backend API (task‑server.js) which persists data in PostgreSQL (or JSON for lightweight setups).

Core concepts:

Project / Board: The dashboard uses a folder-style hierarchy. Parent boards act like folders and child boards roll up into their workspace tree.
Task: Unit of work with title, description, labels, status, priority, owner, preferred OpenClaw model, dates, dependencies, and subtasks.
View: Different visualizations of the same task data: List, Board, Timeline, Agent, Audit.

Views

List View (Default)

Displays tasks as a vertical list. Supports:

Hierarchical nesting: subtasks are indented under their parent with a chevron to collapse/expand.
Quick toggles: checkboxes to mark complete, edit, delete.
Color‑coded priority badges (low/medium/high/critical) – configurable in CSS.
Overdue highlighting (red border when due_date is past and not completed).

Use the toolbar to sort by newest, oldest, recently updated, or alphabetical.

Board View (Kanban)

Columns represent workflow states: backlog, ready, in_progress, blocked, review, completed.

Drag tasks between columns to change status.
Dropping a task updates its status and updated_at.
Undo toast appears briefly; click to revert.

Note: Board view requires the /api/views/board endpoint with a project_id query parameter. In the current self‑contained version, the placeholder will be replaced once the view module is fully integrated.

Timeline View (Gantt)

Visualize tasks with start_date and due_date as bars on a chronological axis.

Dependencies are drawn as arrows.
You can drag bars to adjust dates (future enhancement).
Tasks without dates appear in an “Unscheduled” column.

Endpoint: /api/views/timeline?project_id=X&start=&end=

Agent View

Select an agent from the dropdown to see their assigned tasks (owner field). Shows:

Total, Ready, In Progress, Completed, Locked by Me.
Claim and release buttons for task execution.
Execute button (triggers OpenClaw task execution with pre‑guard).

The agent view polls every 30 s when active (heartbeat). You can pause updates with the “Pause” button.

Audit View

A full change log of task and project modifications. Each entry shows:

Timestamp
Actor (user or agent)
Action (created, updated, deleted, status changed, etc.)
Task ID
Details: old → new values (concise diff)

Supports server‑side filters via query parameters: task_id, actor, action, start_date, end_date, limit, offset.

Cron View

Monitor and control scheduled cron jobs from within the dashboard.

Click the ⏱️ Cron button in the toolbar to open the Cron view.
The view lists all cron jobs defined in the crontab/ directory:
- Job ID (filename)
- Name (optional, from comment)
- Schedule (cron expression)
- Last run time and exit status
- Next scheduled run (if enabled)
For each job you can:
- Run Now – manually trigger immediate execution (bypasses schedule)
- View Logs – see recent output from the job’s last runs (tails stdout/stderr)
The view refreshes automatically when changes are made.

Endpoints: GET /api/cron/jobs, GET /api/cron/jobs/:id/runs, POST /api/cron/jobs/:id/run.

Task Operations

Add a Task

Open the task composer at the top of the page.
Enter a title and optional description.
Optionally set labels, status, priority, owner, preferred model, recurrence, start date, and due date.
Click Add Task.

The task appears at the top of the list (sorted by newest by default).

Edit a Task

Click the pencil icon on a task card. The inline editor lets you modify:

Title
Description
Labels / category
Status
Priority
Owner
Preferred OpenClaw model
Start date and due date
Recurrence

Press Enter (Save) or Escape (Cancel).

Delete a Task

Click the trash icon. Confirm the dialog. Deletion is permanent.

Complete / Undo

Click the check‑circle button to toggle completion. Completed tasks gain a strikethrough and move according to the current filter.

Filtering & Search

Status Filters

All – all active tasks (excludes archived)
Pending – not completed
Completed – completed tasks (still active, not archived)
Archived – tasks marked as archived (historically completed)

Each button shows a count badge. The active filter is highlighted.

Select a category from the dropdown to show only tasks belonging to that category.

Search

Type in the search box to match task title or category (case‑insensitive). The results update as you type (debounced 300 ms).

Archive Workflow

Instead of deleting completed tasks, the dashboard uses a two‑step history preservation:

completing a task marks completed = true (but archived = false).
“Archive completed” button (formerly “Clear completed”) moves all completed tasks to the archive by setting archived = true for each.

Archived tasks:

Are excluded from All/Pending/Completed filters.
Appear only when you select the “Archived” filter.
Remain searchable (if you include archived in the filter).
Can be viewed in the Audit view with full history.

This ensures you retain a referenceable history without cluttering daily work.

Keyboard Shortcuts

For power users and accessibility:

Key	Action
`Ctrl+K` / `Cmd+K`	Open the command palette
`Tab` (in the palette)	Toggle between Search and Ask mode
`N`	Focus the new task input
`1`	Switch to List view
`2`	Switch to Board view
`3`	Switch to Timeline view
`4`	Switch to Agent view
`5`	Switch to Audit view
`J`	Move focus to next task in the list
`K`	Move focus to previous task
`Esc`	Clear search input and reset filter to “All”

Shortcuts are ignored when you are typing inside an input, textarea, or select element.

One-Click Actions & Confirmations

Consequential operator actions (assign a task, dispatch a run, decide an approval, cancel or re-dispatch a run) all travel one governed path: a typed envelope → confirmation matched to severity → idempotent execution → a receipt. The raw endpoints stay available to scripts and agents; the buttons below are the operator surface of that gate (design brief: docs/briefs/one-click-actions.md).

Where the actions live

Action	Where	Confirmation
Assign task owner	Tasks view — edit form owner select (set/change only; unassign stays a plain save)	Single click
Dispatch workflow run	Agent Queue / Agents view — “⚡ Run workflow…” on each task card	Template picker → preview modal
Approve / Reject approval	Approvals view cards	Preview modal
Cancel run	Workflows view run rows (⛔ on queued/running/blocked/retrying runs)	Hold-to-confirm
Re-dispatch failed run	Workflows view failed rows (↻)	Preview modal

Confirmation modes

Single click (low severity, reversible): assigning a task owner fires immediately; the toast tells you the recovery move (re-assign).
Preview modal (medium severity): exactly what will happen, on which target, with which params, plus the rollback hint — nothing fires until you press Confirm. Esc, the backdrop, or Cancel dismisses with zero network requests.
Hold-to-confirm (high severity: cancelling a run destroys paid in-flight work): press and hold the round button for 1.2 s while the ring fills; release early and nothing happens. Keyboard parity: focus the button (Tab), then press and hold Enter for the same 1.2 s — keydown starts, keyup releases. Esc cancels.

Outcomes, receipts, and the Recent-actions tray

Every executed action writes an immutable receipt (kind, target, actor, outcome, rollback hint) mirrored into the audit log as action.<kind> — visible in History → Audit Log like any other entry.

Toasts confirm success (with the recovery hint), replayed duplicates (“already executed — no side effect”), governance rejections, and failures.
Budget blocks render a distinct amber banner naming the budget, its period, and % of cap — not a generic error. Nothing was dispatched; after a cap raise (Mission Control cost panel) simply retry the action.
Recent-actions tray (⚡ button in the taskbar): the last 10 receipts, newest first — outcome icon, action label, target, relative time; click a row to expand the rollback hint and jump to the owning view (run → Workflows, task → Tasks, approval → Approvals). The list refreshes when opened; actions you fire while it is open appear immediately.

Retries vs repeats

Retrying a timed-out action is safe: the same confirmed intent carries the same receipt id, and the server replays the stored receipt instead of executing twice. Deliberately repeating an action (e.g. dispatching the same template again) mints a fresh intent and executes again — both receipts stay in the tray.

Ask Bar (NL Commands)

The command palette (Ctrl+K / Cmd+K) has two modes. Search finds and navigates; Ask understands intents in plain language and proposes actions through the exact same governed path the buttons use (design brief: docs/briefs/nl-command-bar.md). Press Tab inside the palette to toggle — the chip next to the hint bar always shows which mode you’re in. There is no implicit switching: typing a search query that happens to contain a verb never turns into an action.

What Ask understands

You type	What happens	Confirmation
“assign checkout bug to kaya”	Assigns the task to agent kaya	Single click
“run nightly backup on task #42”	Dispatches template on the task	Preview modal
“approve the deployment request” / “reject …”	Decides a pending approval	Preview modal
“cancel run 4f2a” / “stop run …”	Cancels a running/queued/waiting run	Hold-to-confirm (1.2 s)
“retry run 4f2a” / “re-dispatch …”	Re-queues a failed run	Preview modal
“spawn agent for checkout bug, report when done” / “create task for invoices” / “add agent for "nightly sync"”	Creates a task titled from your sentence (everything after “for”, quotes honored) in the default project	Single click
“what’s running” / “fleet status”	Inline answer: running runs + busy agents	Read-only
“show failed runs” / “what failed”	Failed runs + re-dispatch chips	Read-only
“pending approvals” / “what needs approval”	Pending approvals + approve chips	Read-only
“budget status” / “am I over budget”	Names breached/amber budgets	Read-only
anything else	Falls back to normal search results	—

Targets resolve against live data: task titles or #id prefixes, run ids (run_…, UUID, short id), approval subjects, agent display names, workflow template names. Quoted strings (“checkout bug”) force literal title matching. Create intents need a title — the words after “for” become it verbatim; with nothing after the noun (just “spawn agent”) Ask degrades to search rather than inventing one. The new task lands in the default project, same as creating from the Tasks view.

The interpretation card

Before anything executes, Ask shows exactly what it understood: the action, the resolved target, the parameters, and the recovery hint. Nothing has fired yet — no envelope exists, zero requests sent. Confirming the card hands off to the standard confirmation gate, so the table’s confirmation column above is the registry’s severity tier, applied unchanged:

Single click actions fire on that confirm.
Preview modal actions open the typed preview next.
Hold-to-confirm (cancel) opens the 1.2 s ring next.

When several targets match (“3 runs match ‘import’”), a pick list appears; Enter does nothing until you pick one. If Ask can’t map your sentence to an action, it says so honestly and shows normal search results for the same text instead of guessing.

What Ask refuses

Batch actions (“cancel all failed runs”) — one action, one target, always.
Scheduling (“every day at 9…”) — recurring schedules live in the Cron view.
Config writes — budgets, settings, snapshot restores are never proposed.
Title-less creation (“spawn agent”) — no title, no task; Ask shows search results instead of guessing.
Unknown agents/templates — named as such, never guessed.

Query answers (“what’s running”, “budget status”) are read-only — they issue only GET requests and never construct an action. Outcomes, receipts, budget-block banners, and the Recent-actions tray behave identically whether an action came from a button or from Ask.

Budget Management

Budgets are named spending rules with automatic enforcement at dispatch time (design brief: docs/briefs/budget-ledger.md). Mission Control shows the read-only bars; the Budgets app (Operations category) is where rules are created and managed.

Reading the list

Every defined budget — active or inactive — renders as a card with its scope (agent: coder, department: …, workflow type: …, or fleet = all agents), period with the current period_key, a spend-vs-cap bar, run count, and the breach action badge:

Green bar — under 75% of cap, routine burn.
Amber bar — strictly above 75% of cap; raise the cap before dispatch holds start.
Red bar + breached badge — at/over cap (exactly-at-cap counts). The action badge shows what enforcement does: pause_new_runs holds new runs in the queue, hard_stop also cancels in-flight runs.
○ inactive — rule exists but does not enforce; history is preserved.

Spend derives live from completed-run cost/token data — in-flight spend appears when runs report usage.

Create a budget

Open Budgets → ＋ New Budget.
Name it, pick a scope, and fill the scope ID (agent name free-text with suggestions; fleet budgets need no ID).
Pick a period (daily/weekly/monthly), enter a cap, and choose USD or tokens — exactly one cap per budget (create two budgets if you want both).
Choose what happens on exceed: warn, pause new runs, or hard stop.
Submit. Validation mirrors the API client-side; anything the server rejects renders inline verbatim.

Scope and period are fixed after creation (they key the one-active-budget-per-scope+period rule) — to change them, deactivate the old budget and create a new one.

Recovering from a breach

There is no un-pause button by design — pause state is recomputed from live spend on every dispatch. Recovery is one of exactly three moves:

Wait for rollover — a new empty period drops spend below cap automatically and held runs drain in order.
Raise the cap — ✎ Edit on the card, enter the new cap (switching USD/tokens replaces the sibling cap), save.
Deactivate — ⏸ Deactivate stops enforcement immediately (confirm dialog; ledger history preserved). ▶ Activate re-enables it.

Ledger drawer

☰ Ledger expands a per-budget audit trail: timestamped enforcement events (warned / paused / hard_stopped / recovered) with the period key and detail payload — the record of what the system did and when.

Without a database

Budget rules need PostgreSQL. In json_snapshot mode the view shows a named “Budgets unavailable” panel instead of an error; nothing else breaks.

Snapshots & Restore (Settings)

Full-state insurance lives in Settings → 💾 Snapshots & Restore (no separate windowed app). A snapshot is a named, versioned, downloadable JSON artifact of every dashboard table plus non-secret settings; restore is preview-first and never writes anything until you confirm.

Create a snapshot

Open Settings → Snapshots & Restore. The name field defaults to snapshot-YYYYMMDD-HHmm — rename it or leave it.
Press Create snapshot. The button disables while generating; on success a toast reports the total row count and the list refreshes.
Each row shows name/id, created time, honest on-disk size, total rows, and the schema verdict from your last preview (not checked until then).
⬇ Download saves the artifact JSON as an attachment — keep copies off-box; that file alone reconstructs the state it captured.

The registry and downloads work even when PostgreSQL is down (they are disk-only). Creating snapshots requires the database.

Restore in three steps

Pick an artifact: “↻ Restore…” on any server-side row, or “📥 Restore from file…” for a downloaded artifact (files over 100 MB are refused client-side before upload).
Read the preview — nothing is written yet: a per-table diff grid (added / updated / conflicts / unchanged, expandable PK samples), the schema-compat badge, and warnings such as target newer (target DB has migrations the artifact predates) or active runs (pause the dispatcher before a destructive replace). The rollback hint reminds you to re-create a snapshot of the current state first — that one click is the honest undo.
Confirm by mode: Merge (default) upserts artifact rows and deletes nothing — a plain Confirm. Replace additionally deletes live rows absent from the artifact — destructive, so the confirm flips to hold-to-confirm: press and hold the red ring for 1.2 s (or focus it and hold Enter); release early and nothing fires. A typed fallback (type REPLACE) exists for keyboards where holding is awkward.

While it runs

A determinate progress bar advances as restore-progress events arrive per completed table. Closing the panel — or the whole window — does not cancel the apply; when you come back, the panel offers to reattach by its restoreId. If a table fails mid-restore, everything committed before it stays committed (that is the resume point, not corruption): press Retry resume and the same restoreId continues at the first incomplete table. Completed restores end in a summary that says plainly whether it finished fresh, resumed from a checkpoint, or was a duplicate replay of an already-finished restore (executing nothing).

Agent Integration

Tasks can be assigned to an agent directly in the composer or edit form. The Agent view lets an agent:

See their queue (tasks where owner = agent_name and status in [ready, in_progress]).
Claim a task (locks it to prevent other agents from taking it).
Release a task (unlock).
Execute a task (triggers OpenClaw execution with pre‑execution guard and QMD context).

The heartbeat automatically refreshes the agent’s task list every 30 seconds unless paused.

Import / Export

Export

JSON: Download the entire task list (including all fields) as a JSON file.
CSV: Download a comma‑separated values file with columns: text, category, completed, archived, createdAt, updatedAt.

Import

Click “Import” and select a previously exported .json or .csv file.
The import merges tasks; existing tasks are matched by id if present, otherwise new tasks are created.

Install as a Desktop App (PWA)

The dashboard is an installable Progressive Web App — it runs in its own window with a launcher icon, no browser chrome, like a native desktop app.

Install

Sign in to the dashboard in Chrome or Edge (the service worker registers only after authentication succeeds).
Open the browser address-bar install icon (⊕ / monitor-with-arrow), or the browser menu → Install OpenClaw Desktop / Cast, save and share → Install page as app.
The app opens in a standalone window and gets its own entry in your OS start menu / dock.

What gets cached

Static assets only (/src/, /lib/, /icons/, the web manifest) are served cache-first from a versioned cache (openclaw-desktop-v1); old versions are deleted automatically on upgrade.
Navigation requests (the app shell) are network-first with cache fallback, so you get fresh UI whenever the server is reachable and last-known UI when it is not.
/api/* is never cached — tasks, auth, and live data always come from the server. Your bearer token is never stored by the service worker.
The app shell itself carries no credentials (the token stays in memory/localStorage via the bootstrap flow), so a cached shell is safe.

Updating & uninstalling

Updates land on reload: sw.js is served Cache-Control: no-cache, so a new deploy is picked up immediately; the worker activates with skipWaiting + clients.claim and purges stale caches.
Uninstall like any app: right-click the launcher icon → uninstall, or edge://apps in Edge / chrome://apps in Chrome.

Appearance: Themes & Accent Packs

The desktop shell ships a dark and a light base theme plus five built-in accent packs layered on top.

Base theme (dark / light)

Toggle with the moon/sun button in the taskbar tray, or press the theme toggle in the Start menu area.
First load follows your system preference; an explicit toggle persists to localStorage (openclaw.win11.theme.v1).

Accent packs

Accents recolor buttons, highlights, selection rings, and active states on top of either base theme:

Pack	Light accent	Dark accent
Blue (default)	`#0067c0`	`#60cdff`
Teal	`#038387`	`#45d1d6`
Violet	`#8661c5`	`#c3a6ff`
Amber	`#ca5010`	`#f7a95d`
Rose	`#c4314b`	`#ff8fa8`

Open the palette icon in the taskbar tray and pick a swatch. The choice persists across reloads (openclaw.accent) and applies before first paint — no flash of the wrong color.
Switching base themes keeps your accent; switching accents keeps your base theme.
An invalid or corrupted stored value falls back silently to the default blue pack.

Accessibility

ARIA labels on interactive elements.
Keyboard navigation supported throughout.
Focus styles are visible.
Color is not the only means of conveying information (e.g., priority badges have text labels when needed).
High‑contrast friendly CSS variables.

Tips & Best Practices

Use categories to group related tasks; they are easy to filter.
Archive completed tasks regularly to keep the active list clean.
Leverage keyboard shortcuts for fast data entry.
In the Audit view, filter by actor to track changes made by a specific agent.
For long‑running tasks, set a due date; overdue tasks are highlighted.

Troubleshooting

Symptom	Likely Cause	Fix
Dashboard fails to load	task‑server.js not running	Start with `dashboard/scripts/dashboard-health.sh start` or `dashboard/scripts/restart-task-server.sh`
No tasks appear	Wrong project selected or database empty	Check API `/api/projects` and set a project in the UI (future multi‑project support)
404 on `/api/views/board`	Storage not initialized or missing endpoint	Ensure `STORAGE_TYPE` and DB connection; check server logs
Changes not persisting	Browser in incognito/private mode or storage disabled	Enable localStorage; check console for quota errors

Next Steps

Multi‑project selection UI
Owner assignment from task edit panel
Recurring task generation
Full Board and Timeline interactivity