MAESTRO: Fix usage-dashboard.md documentation inaccuracies

- Add missing "Sessions" summary card (6 cards total, not 5)
- Document Location Distribution chart (local vs SSH queries)
- Document Peak Hours chart (24-hour activity breakdown)
- Document Duration Trends chart in Overview tab
- Expand Agents tab with Session Statistics details
- Expand Auto Run tab with all 6 metric cards and mini chart
- Add Keyboard Navigation section (tab navigation, section nav)
- Fix Accessibility section (colorblind mode not in Settings UI)
- Fix Enabling/Disabling Collection path (General tab → Usage Dashboard)
- Add real-time updates and database size footer documentation
This commit is contained in:
Pedram Amini
2026-01-11 06:27:22 -06:00
parent d10ffc29b6
commit c42bf3224b

View File

@@ -34,6 +34,7 @@ The dashboard is organized into four tabs, each providing different insights int
The Overview tab gives you a high-level summary of your AI usage:
**Summary Cards:**
- **Sessions** — Total number of registered sessions
- **Total Queries** — Number of messages sent to AI agents
- **Total Time** — Cumulative time spent waiting for AI responses
- **Avg Duration** — Average response time per query
@@ -50,16 +51,31 @@ A donut chart breaking down your queries by source:
Toggle between **Count** (number of queries) and **Duration** (time spent) views.
**Location Distribution:**
A donut chart showing the breakdown between local and remote (SSH) queries. Useful for understanding how much work is done locally versus on remote machines.
**Peak Hours:**
A 24-hour bar chart showing when you're most active. Each bar represents an hour of the day (023), with height indicating query count or duration. The peak hour is highlighted. Toggle between Count and Duration views.
**Activity Heatmap:**
A GitHub-style heatmap showing your activity patterns throughout the week. Each cell represents an hour of the day, with color intensity indicating activity level. Toggle between Count and Duration views to see different perspectives.
**Duration Trends:**
A line chart showing how your query durations vary over time. Useful for spotting performance trends or changes in workload.
### Agents
The Agents tab provides detailed per-agent analytics:
- Individual statistics for each AI agent
- Query counts, total time, and average duration per agent
- Comparison charts for side-by-side analysis
**Session Statistics:**
- **Total Sessions** — Count of registered sessions
- **By Agent** — Breakdown by agent type (Claude Code, Codex, etc.) with color-coded indicators
- **Git Repos vs Folders** — How many sessions are Git repositories versus plain directories
- **Remote vs Local** — Sessions running on remote SSH hosts versus local machine
**Agent Comparison:**
- Full agent comparison chart showing query counts and time spent per agent
- Side-by-side visual comparison of your agent usage patterns
### Activity
@@ -73,9 +89,16 @@ The Activity tab shows your usage patterns over time:
The Auto Run tab focuses specifically on automated playbook execution:
- Auto Run session statistics
- Task completion rates
- Time spent on automated vs. interactive work
**Metric Cards:**
- **Total Sessions** — Number of Auto Run batch sessions
- **Tasks Done** — Total tasks completed (with attempted count)
- **Avg Tasks/Session** — Average tasks completed per Auto Run session
- **Success Rate** — Percentage of tasks that completed successfully
- **Avg Session** — Average duration of an Auto Run session
- **Avg Task** — Average duration per individual task
**Tasks Completed Over Time:**
A mini bar chart showing task completions by date (last 14 days). Hover over bars to see exact counts and success percentages for each day.
## Time Range Filtering
@@ -91,6 +114,17 @@ Use the time range dropdown in the top-right corner to filter all dashboard data
The selected time range applies to all tabs and charts. Your preferred time range is saved and restored between sessions.
## Keyboard Navigation
| Shortcut | Action |
|----------|--------|
| `Cmd+Shift+[` / `Ctrl+Shift+[` | Previous tab |
| `Cmd+Shift+]` / `Ctrl+Shift+]` | Next tab |
| `Arrow Up/Down` | Navigate between chart sections |
| `Home` | Jump to first section |
| `End` | Jump to last section |
| `Esc` | Close dashboard |
## Exporting Data
Click **Export CSV** in the top-right corner to download your usage data as a CSV file. The export includes:
@@ -116,7 +150,7 @@ The Usage Dashboard collects:
- Message content (your prompts and AI responses)
- File contents or paths
- Token counts or costs (tracked separately per-session)
- Token counts or costs (tracked per-session in the main UI, not aggregated in the dashboard)
- Activity outside of Maestro
### Enabling/Disabling Collection
@@ -124,22 +158,34 @@ The Usage Dashboard collects:
Stats collection is enabled by default. To disable:
1. Open **Settings** (`Cmd+,` / `Ctrl+,`)
2. Find **Stats Collection**
3. Toggle off to stop collecting usage data
2. Go to the **General** tab
3. Find **Usage Dashboard** section (marked with Beta badge)
4. Toggle off **Enable stats collection**
You can also set your **Default dashboard time range** here (Today, This Week, This Month, This Year, or All Time).
Disabling collection stops new data from being recorded but preserves existing data in the dashboard.
## Accessibility
The Usage Dashboard supports colorblind-friendly palettes:
The Usage Dashboard supports colorblind-friendly chart palettes using high-contrast colors from the Wong palette. This mode is enabled programmatically via the `colorBlindMode` setting.
1. Open **Settings** (`Cmd+,` / `Ctrl+,`)
2. Enable **Colorblind Mode**
3. Charts will use high-contrast colors from the Wong palette
<Note>
The colorblind mode setting is available in the application configuration but not yet exposed in the Settings UI. It will use accessible colors automatically when enabled.
</Note>
## Additional Features
**Real-time Updates:**
The dashboard automatically refreshes when new queries are recorded. An "Updated" indicator briefly appears when new data arrives.
**Database Size:**
The footer displays the current size of the stats database, helping you monitor storage usage over time.
## Tips
- **Check the Activity Heatmap** to understand your most productive hours
- **Use Peak Hours** to identify your most productive time of day
- **Compare agents** to see if one consistently performs faster than others
- **Monitor Auto Run vs. Interactive** ratio to understand your automation level
- **Export regularly** if you want to track long-term trends externally