Skip to content

Syce Overview (Rust)

Syce is a real-time terminal UI (TUI) for monitoring Horsies workers, tasks, and workflows. Built in Rust with ratatui, it connects directly to the Horsies PostgreSQL database and renders live cluster state in the terminal.

The current Syce release does not support the alpha.26 task-history schema. It reads terminal tasks from horsies_tasks, but that table now stores live work only. Do not use Syce for complete task or result views until a compatible release is available.

Terminal window
cargo install syce
Terminal window
cd syce
cargo build --release

The binary is at target/release/syce.

Syce needs the same PostgreSQL database URL used by Horsies workers.

Terminal window
export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
syce
Terminal window
syce --database-url "postgresql://user:pass@localhost:5432/mydb"
Flag Default Description
--database-url, -d $DATABASE_URL PostgreSQL connection string
--tick-rate, -t 4.0 Data refresh rate (ticks per second)
--frame-rate, -f 60.0 UI render rate (frames per second)

Syce organizes monitoring into five tabs, accessible via number keys 1-5.

Cluster-level overview:

Syce Dashboard

  • Cluster Capacity – Active workers, total capacity, utilization percentage, running tasks
  • Task Status Distribution – Breakdown by status (Pending, Claimed, Running, Completed, Failed)
  • Workflow Summary – Workflow counts by status
  • Utilization Trend – Braille line chart of cluster utilization over the past hour
  • Active Alerts – Overloaded workers and stale claim warnings

Per-worker monitoring:

Syce Workers Tab

  • Worker list with hostname, PID, process count, running/claimed tasks, CPU/memory usage, uptime
  • Select a worker to see detailed metrics and load charts
  • Adjustable time window for charts: 5m, 30m, 1h, 6h, 24h

Task distribution and inspection:

Syce Tasks Tab

  • Aggregated task breakdown by worker
  • Status filters (Pending, Claimed, Running, Completed, Failed)
  • Expand a worker row to see individual task IDs
  • Task detail modal with full JSON payload
  • Copy task data to clipboard

Workflow tracking:

Syce Workflows Tab

  • Workflow list with ID, name, status, task count, progress
  • Status filters (Pending, Running, Completed, Failed, Paused, Cancelled)
  • Workflow detail modal showing constituent tasks and their states
  • Copy workflow data to clipboard

Syce Workflow Detail

Operational health:

  • Snapshot age distribution (histogram of worker state freshness)
  • Dead worker detection
Key Action
1-5 Switch tab
/ Search (context-aware)
? Toggle help overlay
r Refresh current tab
t Cycle theme
q, Esc Quit
Ctrl+z Suspend to background
Key Action
Up/Down Select worker
[, ] Cycle time window (5m / 30m / 1h / 6h / 24h)
Key Action
Up/Down Navigate workers / task IDs
Enter Expand row / open task detail
Esc Collapse expanded row
y Copy task JSON to clipboard (in detail view)
Key Action
p Toggle Pending
c Toggle Claimed
u Toggle Running
o Toggle Completed
f Toggle Failed
a Select all statuses
n Clear all statuses
Key Action
Up/Down Navigate workflows
Enter Open workflow detail
Esc Close detail
y Copy workflow JSON to clipboard

Syce ships with Catppuccin color themes. Press t to cycle through available flavors (Latte, Frappe, Macchiato, Mocha) with automatic light/dark detection.

Syce reads from the same PostgreSQL tables Horsies workers write to:

Table Purpose
horsies_worker_states Worker state snapshots (captured every 5s)
horsies_tasks Live task records only
horsies_task_history Terminal task records; unsupported by the current Syce release
horsies_heartbeats Task liveness heartbeats
horsies_workflows Workflow definitions and status
horsies_workflow_tasks Individual workflow task records
horsies_schedule_state Scheduler execution state