automaton/automaton/dashboard

Automaton Dashboard

Interactive web dashboard for monitoring automaton framework task progress.

Installation

The dashboard is part of the automaton framework. No separate installation is needed.

# From your automaton installation directory
python -m automaton.dashboard

Usage

# Start from the current directory
python -m automaton.dashboard

# Start from a specific project directory
python -m automaton.dashboard /path/to/project

# Custom host/port
python -m automaton.dashboard --host 0.0.0.0 --port 3000

The dashboard opens in your browser at http://localhost:8080.

Scope-Aware

The dashboard automatically detects its scope based on the current working directory:

• Framework mode: When run from ~/.automaton/, tracks framework development tasks
• Project mode: When run from a project root (a project that has installed automaton), tracks that project's tasks

Views

Board View (Default)

The primary Kanban board view showing tasks organized by their current phase:

  Backlog (0)  │  Research (1)  │  Design (0)  │  Implement (0)  │  Done (1)  │  Blocked (1)
  ──────────────│────────────────│──────────────│─────────────────│──────────────│──────────────
  — empty —     │ ▸ research-   │              │                 │ ✅ implement │ ❌ bad-impl
                │   task        │              │                 │   task       │
                ────────────────│───────────────│─────────────────│──────────────│──────────────
                ─ empty —       │               ────────────────  │──────────────│──────────────

Statistics View

Shows task statistics including phase distribution, pass/fail rates, and sub-task statistics.

Timeline View

Shows task progress through phases as a timeline with wave visualization for decomposed tasks.

Keyboard Shortcuts

Key	Action
Space	Cycle views (Board → Stats → Timeline)
1	Board view
2	Statistics view
3	Timeline view
t	Cycle themes (default → dark → light)
r	Manual refresh
f	Toggle filter bar
s	Focus search
?	Show help
Esc	Close modals / clear search
q	Quit

Configuration

Create a dashboard-config.json file in your project's .automaton/ directory:

{
    "auto_refresh_interval": 2,
    "default_view": "board",
    "column_width": 30,
    "show_timelines": true,
    "theme": "default"
}

Configuration Options

Option	Type	Default	Description
auto_refresh_interval	int	2	Seconds between auto-refreshes (1-60)
default_view	string	"board"	View to show on startup
column_width	int	30	Minimum width of each column in characters
show_timelines	bool	true	Show time elapsed on cards
theme	string	"default"	Color theme ("default", "dark", "light")

Color Themes

• Default: Bright colors on dark background
• Dark: Dimmed colors for a darker appearance
• Light: Softer colors for light terminals

Phase Mapping

Kanban Column	Automaton State	Artifact
Backlog	New	No artifacts
Research	Research	SPEC.md
Decomposition	Decomposition	SPEC.md + DECOMPOSITION.md
Design	Design	DESIGN.md
Test Design	Test Design	TEST_PLAN.md
Implement	Implement	IMPLEMENTATION.md
Bug Find	Bug Find	BUG_REPORT.md
Adversarial Bug Find	Adversarial Bug Find	ADVERSARIAL_BUG_REPORT.md
Doc Review	Doc Review	DOC_REVIEW.md
Referee	Referee	VERDICT.md
Done	Complete	VERDICT.md (PASS)
Blocked	Human Intervention	VERDICT.md (FAIL/NEEDS_REVIEW)

Architecture

automaton/dashboard/
├── __init__.py          # Package marker
├── __main__.py          # Entry point (python -m automaton.dashboard)
├── config.py            # Configuration management
├── themes.py            # Color themes (for TUI fallback)
├── pyproject.toml       # Python package config
├── README.md            # This file
├── core/
│   ├── scope.py         # Scope detection (framework vs project mode)
│   ├── task.py          # Task model, state machine, artifact parsing
│   ├── board.py         # Kanban board logic
│   ├── stats.py         # Statistics calculations
│   ├── timeline.py      # Timeline data
│   └── refresh.py       # File system watcher (for future use)
└── ui/
    ├── app.py           # Web server (HTTP + API endpoints)
    └── html/
        ├── index.html   # Dashboard UI
        ├── styles.css   # All styling (3 themes via CSS variables)
        └── dashboard.js # All UI logic (Kanban, stats, timeline, filtering)

Non-Goals

• Real-time collaboration — single-user only
• Task creation/editing — read-only view
• Notification system — no push notifications
• Calendar integration — no date-based scheduling
• External PM tool integration — standalone only