Web Dashboard

The web dashboard is a browser UI for monitoring and managing Cloche runs. It gives you live log streaming, workflow visualization, token usage metrics, task management, and container controls — all without needing the CLI.

Enabling the Dashboard

cloche init creates ~/.config/cloche/config with the dashboard enabled on localhost:8080 by default. Start the daemon and open http://localhost:8080.

To enable it manually, set http in ~/.config/cloche/config:

[daemon]
http = "localhost:8080"

Or pass it as an environment variable:

CLOCHE_HTTP=localhost:8080 cloched

The dashboard is not started if http is unset (and CLOCHE_HTTP is not set). Choose any available port. The CLI commands cloche tasks and cloche health also require CLOCHE_HTTP to be set, since they talk to the daemon’s HTTP API.

Pages

Projects

The landing page shows a card for each registered project. Each card displays:

• A health dot (green = healthy, yellow = degraded, red = failing) based on recent pass/fail rates.
• Pass stats — how many of the last 10 runs succeeded.
• Active run count — runs currently in progress.
• Run history dots — a mini visual history of recent run outcomes.
• A View Runs link to the filtered runs list for that project.
• A Trigger Orchestrator button that kicks off the orchestration loop immediately. Shows “Dispatched N” on success or “No tasks ready” if nothing was dispatched.

Click a project card to go to the Project Detail page.

Project Detail

A four-panel page for a specific project. A Start Loop / Stop Loop toggle button at the top controls the orchestration loop.

Project Info

Shows the Docker image (parsed from the project’s Dockerfile), the project version, and all prompt files under .cloche/prompts/. For each prompt file you can:

• Expand to read its current content.
• View git history — commits that touched the file, with short SHA, date, and message.
• Click a commit to load an inline unified diff.

Token Burn

Shows token usage data for the project:

• 1-hour burn rate — tokens consumed per hour across all agents in the last hour.
• 24-hour totals — total input and output tokens per agent over the last 24 hours.

Each row shows the agent name, input tokens, output tokens, and combined total. Values are formatted with K/M suffixes (e.g. 1.5M).

In-progress Tasks

Tasks that have been assigned to a worker and have an active run. Shows task ID, title, status, assignment time, and a link to the active run.

Releasing a stale task: If a task is assigned but its run is no longer active (e.g. after a daemon restart), a Release button appears. Clicking it triggers the project’s release-task workflow to return the task to open status in your tracker.

Upcoming Tasks

Tasks returned by list-tasks that have not yet been assigned. Both task panels refresh automatically.

Workflow DAG

A visual graph of the project’s workflows. If the project has both container and host workflows, tabs let you switch between them.

The graph shows:

• Nodes — each step, labeled with its name and a type icon (agent, script, workflow dispatch).
• Edges — wires between steps, labeled with the result name. Colors: green for success, red for failure, other colors for custom results.
• Terminal nodes — done and abort rendered distinctly at the bottom of the graph.

Click any step node to open a drawer panel with the step’s name, type, declared results, max_attempts if set, and the full prompt/script/workflow contents.

Runs

The runs list groups workflow executions by task and attempt. Each group shows:

• A task header with task ID, title, and overall status.
• Attempt blocks under each task, with timestamp and aggregate status. The latest attempt is expanded; earlier ones are collapsed.
• Run rows within each attempt — the top-level run (e.g. main) and any child runs it dispatched (e.g. develop).

Click an attempt header to expand or collapse it. Runs with no associated task appear below as ungrouped entries. Use the project filter dropdown to limit the view.

Run Detail

Full detail of a single workflow execution.

Steps Table

A table of all steps with name, result, duration, and (for agent steps) token usage. Click any row to expand an output panel showing the captured log for that step. The output panel streams live during active steps.

For runs that dispatch child workflows, the steps table shows a tree view: child-run steps appear indented below the workflow step that spawned them.

Log Viewer

A scrollable log panel streams all output for the run in real time via SSE. Each line is labeled with its type (script output, LLM conversation, status event). Use Load Earlier to fetch older log lines.

Container Management

A Delete container button appears when the container is retained. Use it to free disk space once you no longer need the container.

Cancelling a Run

A Cancel button appears for pending or active runs. Clicking it stops the run and marks it cancelled.

Task Detail

Shows all attempts for a task, newest first. Each attempt row shows the attempt ID, start time, duration, and result. Click an attempt to expand a list of workflow runs and steps within it.

Failed Open Tasks

A dashboard at /failed-tasks that surfaces tasks attempted at least once but never succeeded and still open in your tracker.

Each row shows: task ID and title, project, failed attempt count, link to the latest run, latest failure timestamp, and a truncated error excerpt. The page auto-refreshes every 5 seconds.

Token Usage Tracking

Cloche tracks token consumption per agent step and exposes aggregate metrics in the dashboard, cloche status, and a gRPC endpoint.

What Is Tracked

Each completed agent step records:

How Tracking Works Per Agent

Claude Code — token usage is extracted automatically from the --output-format stream-json result event. No extra configuration needed.

Other agents — use the usage_command step config key (or set it globally in config.toml under [agents.<name>]) to run a shell command after each agent step. The command must print JSON to stdout:

{"input_tokens": 1234, "output_tokens": 567}

If the command is absent or fails, usage for that step is not tracked. Execution continues normally.

Token Usage in cloche status

Overview mode (cloche status with no arguments) shows a per-agent burn rate at the bottom if any usage data exists for the last hour:

Token usage (last 1h):
  claude     4,521 in / 2,103 out   6,624 total   ~18.2k/hr
  codex      1,200 in /   890 out   2,090 total   ~5.7k/hr

Task status (cloche status <task-id>) includes a Tokens line:

Tokens:  8,714 (claude: 6,624 / codex: 2,090)

GetUsage gRPC Endpoint

The daemon exposes a GetUsage RPC on the ClocheService for programmatic access:

rpc GetUsage(GetUsageRequest) returns (GetUsageResponse);

message GetUsageRequest {
  string project_dir    = 1; // empty = global (all projects)
  string agent_name     = 2; // empty = all agents
  int64  window_seconds = 3; // 0 = all time; >0 = seconds back from now
}

message GetUsageResponse {
  repeated UsageSummary summaries = 1;
}

message UsageSummary {
  string agent_name    = 1;
  int64  input_tokens  = 2;
  int64  output_tokens = 3;
  int64  total_tokens  = 4;
  double burn_rate     = 5; // tokens per hour (0 when window_seconds = 0)
}

Features at a Glance