Skip to main content

Web UI

SPECA is CLI-first, but ships with speca-web so you can drive the pipeline from a browser. The positioning is strictly CLI Client — the same operations you would run via scripts/run_phase.py or speca-cli (issue #3), surfaced as web pages.

SPECA dashboard

What you can do​

  • Browse past audit runs and inspect their detail
  • Watch phase progress live over WebSocket
  • Filter / sort / Markdown-export findings
  • Kick off a new audit from the picker or guided wizard
  • Chat with Claude / Codex / Gemini / Ollama / Copilot from the right-rail panel (switchable in Settings)
  • Switch runtime / theme (light/dark/system/solarized) / language (EN/JA) from Settings

For the full feature list see Web UI features; for runtime switching see Multi-runtime backends.

Launching​

uv run speca-web --port 7411 --host 127.0.0.1 --serve-frontend

Open http://127.0.0.1:7411/. If claude auth status reports logged_in=true, you land directly on the dashboard; otherwise the login screen offers a paste-code OAuth flow and an API-key form:

Login screen with paste-code OAuth

Localhost only by default​

The server binds 127.0.0.1 by default. To expose it on a LAN, pass --host 0.0.0.0 explicitly — and only in environments where firewall / NAT protection is in place.

Run detail — phase progress + budget gauge​

Run detail with phase rows and budget gauge

Phase rows are collapsible. With one focused, l scrolls the log pane into view and f force re-runs just that phase. Clicking the budget gauge opens a cap-bump modal that raises / clears max_budget_usd:

Budget cap-bump modal

Findings — DSL filter + code highlighting​

The findings list filters server-side by severity / verdict / phase chips and layers a richer client-side DSL on top (path globs, etc.). Markdown export is one click:

Findings list

Clicking a row opens the detail page with the evidence_snippet highlighted by Prism (Solidity / TS / JS / Python / Rust / Go / Java / C / C++):

Finding detail with code highlight

Chat panel — multi-runtime​

Click Chat in the header (or press c) to open the right-rail chat panel:

Chat panel

The backend that drives the conversation is chosen in Settings — five backends are available: Claude / Codex / Gemini / Ollama / Copilot. See Multi-runtime backends for the full story.

Settings — runtime / theme / language​

Runtime selector in Settings

The Chat runtime section is a 5-way switch with availability badges (✓ / !) so you can see at a glance which backend is ready to go. Expand Advanced to override the model or Ollama host per runtime.

Theme: light / dark / system + Solarized:

DefaultSolarized
dashboard defaultdashboard solarized

Toggle from the header L D A S buttons:

Theme toggle 4 buttons

Keyboard shortcuts​

? always opens the cheat sheet:

Keyboard shortcuts help

KeyAction
?Keyboard-shortcut help modal
EscClose any open modal / chat panel
cToggle chat panel
g r / g s / g dNavigate to Runs / Settings / Diagnostics
/Focus findings filter
j / kMove to next / previous finding row
Phase row focus + l / fExpand log / force re-run that phase

All shortcuts are IME-safe (suppressed during composition).

Architecture​

  • Backend — FastAPI + uvicorn (web/server/). Runs scripts/run_phase.py as a subprocess; never imports orchestrator Python code directly.
  • Frontend — React 19 + TypeScript + Vite (web/frontend/). TanStack Query for REST + WebSocket, Zustand for UI state, i18next for EN/JA.
  • State — .speca/runs/<run_id>/state.json for run state, ~/.speca/chat/<conversation_id>.json for chat history, ~/.speca/runtime.json for runtime preferences. No secrets in any of these.

See also​