## CHANGES

- Added brand-new Usage Dashboard with deep analytics across all sessions 📊 - Overview tab shows totals, top agent, sources, and durations at-a-glance 🧾 - Activity heatmap reveals hourly/weekly usage patterns for smarter scheduling 🗓️ - Agent comparison charts help benchmark performance and response-time trends 🧪 - Dedicated Auto Run insights highlight automation time and completion rates 🤖 - Time-range filtering (today→all time) syncs across every dashboard view ⏱️ - One-click CSV export makes sharing and offline analysis effortless 📤 - New keyboard shortcut opens dashboard instantly: Opt+Cmd+U / Alt+Ctrl+U ⌨️ - Remote git worktree creation now supports SSH sessions via remote IDs 🔐 - Worktree sessions now inherit SSH config for smoother remote workflows 🧷
2026-03-10 08:31:19 +00:00 · 2025-12-31 15:29:15 -06:00
parent dc6f8f5912
commit e1d8ec91ea
6 changed files with 177 additions and 12 deletions
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -62,6 +62,7 @@
              "history",
              "context-management",
              "document-graph",
+              "usage-dashboard",
              "autorun-playbooks",
              "playbook-exchange",
              "git-worktrees",
--- a/docs/features.md
+++ b/docs/features.md
@@ -30,6 +30,7 @@ icon: sparkles
 - 🔊 **Speakable Notifications** - Audio alerts with text-to-speech announcements when agents complete tasks.
 - 🎨 **[Beautiful Themes](https://github.com/pedramamini/Maestro/blob/main/THEMES.md)** - 12 themes including Dracula, Monokai, Nord, Tokyo Night, GitHub Light, and more.
 - 💰 **Cost Tracking** - Real-time token usage and cost tracking per session and globally.
+- 📊 **[Usage Dashboard](./usage-dashboard)** - Comprehensive analytics for tracking AI usage patterns. View aggregated statistics, compare agent performance, analyze activity heatmaps, and export data to CSV. Access via `Opt+Cmd+U` / `Alt+Ctrl+U`.
 - 🏆 **[Achievements](./achievements)** - Level up from Apprentice to Titan of the Baton based on cumulative Auto Run time. 11 conductor-themed ranks to unlock.

 > **Note**: Maestro supports Claude Code, OpenAI Codex, and OpenCode as providers. Support for additional providers (Aider, Gemini CLI, Qwen3 Coder) may be added in future releases based on community demand.
--- a/docs/keyboard-shortcuts.md
+++ b/docs/keyboard-shortcuts.md
@@ -28,6 +28,7 @@ The command palette is your gateway to nearly every action in Maestro. Press `Cm
 | Open Settings | `Cmd+,` | `Ctrl+,` |
 | Open Agent Settings | `Opt+Cmd+,` | `Alt+Ctrl+,` |
 | View All Agent Sessions | `Cmd+Shift+L` | `Ctrl+Shift+L` |
+| Usage Dashboard | `Opt+Cmd+U` | `Alt+Ctrl+U` |
 | Jump to Bottom | `Cmd+Shift+J` | `Ctrl+Shift+J` |
 | Cycle Focus Areas | `Tab` | `Tab` |
 | Cycle Focus Backwards | `Shift+Tab` | `Shift+Tab` |
--- a/docs/screenshots/usage-dashboard.png
+++ b/docs/screenshots/usage-dashboard.png
--- a/docs/usage-dashboard.md
+++ b/docs/usage-dashboard.md
@@ -0,0 +1,146 @@
+---
+title: Usage Dashboard
+description: Track and analyze your AI agent usage patterns with comprehensive analytics and visualizations.
+icon: chart-line
+---
+
+The Usage Dashboard provides comprehensive analytics for tracking your AI usage patterns across all sessions. View aggregated statistics, compare agent performance, and explore activity patterns over time.
+
+![Usage Dashboard](./screenshots/usage-dashboard.png)
+
+<Note>
+The Usage Dashboard only tracks activity from within Maestro. It does not include historical data from before you started using Maestro, nor does it capture usage from agents run outside of Maestro (e.g., directly from the command line).
+</Note>
+
+## Opening the Dashboard
+
+**Keyboard shortcut:**
+- macOS: `Opt+Cmd+U`
+- Windows/Linux: `Alt+Ctrl+U`
+
+**From the menu:**
+1. Click the hamburger menu (☰) in the top-left corner
+2. Select **Usage Dashboard**
+
+**From Quick Actions:**
+- Press `Cmd+K` / `Ctrl+K` and search for "Usage Dashboard"
+
+## Dashboard Tabs
+
+The dashboard is organized into four tabs, each providing different insights into your usage:
+
+### Overview
+
+The Overview tab gives you a high-level summary of your AI usage:
+
+**Summary Cards:**
+- **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
+- **Top Agent** — Your most-used AI agent
+- **Interactive %** — Percentage of queries from interactive (non-Auto Run) sessions
+
+**Agent Comparison:**
+A horizontal bar chart showing usage distribution across your AI agents. See at a glance which agents you use most, with query counts and time spent per agent.
+
+**Source Distribution:**
+A donut chart breaking down your queries by source:
+- **Interactive** — Manual queries from AI Terminal conversations
+- **Auto Run** — Automated queries from playbook execution
+
+Toggle between **Count** (number of queries) and **Duration** (time spent) 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.
+
+### 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
+
+### Activity
+
+The Activity tab shows your usage patterns over time:
+
+- Duration trends chart showing how your usage varies
+- Time-based filtering to spot patterns
+- Useful for understanding your productivity cycles
+
+### Auto Run
+
+The Auto Run tab focuses specifically on automated playbook execution:
+
+- Auto Run session statistics
+- Task completion rates
+- Time spent on automated vs. interactive work
+
+## Time Range Filtering
+
+Use the time range dropdown in the top-right corner to filter all dashboard data:
+
+| Range | Description |
+|-------|-------------|
+| **Today** | Current day only |
+| **This Week** | Current week (default) |
+| **This Month** | Current calendar month |
+| **This Year** | Current calendar year |
+| **All Time** | Everything since you started using Maestro |
+
+The selected time range applies to all tabs and charts. Your preferred time range is saved and restored between sessions.
+
+## Exporting Data
+
+Click **Export CSV** in the top-right corner to download your usage data as a CSV file. The export includes:
+
+- Query timestamps
+- Agent information
+- Duration metrics
+- Source categorization (interactive vs. Auto Run)
+
+Use exported data for further analysis in spreadsheet applications or to share usage reports.
+
+## Data Collection
+
+### What's Tracked
+
+The Usage Dashboard collects:
+
+- **Query events** — Each message sent to an AI agent, including duration and which agent handled it
+- **Auto Run sessions** — Start/end times of automated playbook runs
+- **Auto Run tasks** — Individual task completions within playbooks
+
+### What's NOT Tracked
+
+- Message content (your prompts and AI responses)
+- File contents or paths
+- Token counts or costs (tracked separately per-session)
+- Activity outside of Maestro
+
+### Enabling/Disabling Collection
+
+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
+
+Disabling collection stops new data from being recorded but preserves existing data in the dashboard.
+
+## Accessibility
+
+The Usage Dashboard supports colorblind-friendly palettes:
+
+1. Open **Settings** (`Cmd+,` / `Ctrl+,`)
+2. Enable **Colorblind Mode**
+3. Charts will use high-contrast colors from the Wong palette
+
+## Tips
+
+- **Check the Activity Heatmap** to understand your most productive hours
+- **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
+- **Use time filtering** to focus on recent activity or see the big picture
--- a/src/renderer/App.tsx
+++ b/src/renderer/App.tsx
@@ -7596,12 +7596,18 @@ function MaestroConsoleInner() {
    const worktreePath = `${basePath}/${branchName}`;
    console.log('[WorktreeConfig] Create worktree:', branchName, 'at', worktreePath);

+    // Get SSH remote ID for remote worktree operations
+    // Note: sshRemoteId is only set after AI agent spawns. For terminal-only SSH sessions,
+    // we must fall back to sessionSshRemoteConfig.remoteId. See CLAUDE.md "SSH Remote Sessions".
+    const sshRemoteId = activeSession.sshRemoteId || activeSession.sessionSshRemoteConfig?.remoteId || undefined;
+
    try {
-      // Create the worktree via git
+      // Create the worktree via git (pass SSH remote ID for remote sessions)
      const result = await window.maestro.git.worktreeSetup(
        activeSession.cwd,
        worktreePath,
-        branchName
+        branchName,
+        sshRemoteId
      );

      if (!result.success) {
@@ -7624,15 +7630,15 @@ function MaestroConsoleInner() {
        saveToHistory: defaultSaveToHistory
      };

-      // Fetch git info for the worktree
+      // Fetch git info for the worktree (pass SSH remote ID for remote sessions)
      let gitBranches: string[] | undefined;
      let gitTags: string[] | undefined;
      let gitRefsCacheTime: number | undefined;

      try {
        [gitBranches, gitTags] = await Promise.all([
-          gitService.getBranches(worktreePath),
-          gitService.getTags(worktreePath)
+          gitService.getBranches(worktreePath, sshRemoteId),
+          gitService.getTags(worktreePath, sshRemoteId)
        ]);
        gitRefsCacheTime = Date.now();
      } catch {
@@ -7682,7 +7688,9 @@ function MaestroConsoleInner() {
        customModel: activeSession.customModel,
        customContextWindow: activeSession.customContextWindow,
        nudgeMessage: activeSession.nudgeMessage,
-        autoRunFolderPath: activeSession.autoRunFolderPath
+        autoRunFolderPath: activeSession.autoRunFolderPath,
+        // Inherit SSH configuration from parent session
+        sessionSshRemoteConfig: activeSession.sessionSshRemoteConfig,
      };

      setSessions(prev => [...prev, worktreeSession]);
@@ -7723,11 +7731,17 @@ function MaestroConsoleInner() {
    const worktreePath = `${basePath}/${branchName}`;
    console.log('[CreateWorktree] Create worktree:', branchName, 'at', worktreePath);

-    // Create the worktree via git
+    // Get SSH remote ID for remote worktree operations
+    // Note: sshRemoteId is only set after AI agent spawns. For terminal-only SSH sessions,
+    // we must fall back to sessionSshRemoteConfig.remoteId. See CLAUDE.md "SSH Remote Sessions".
+    const sshRemoteId = createWorktreeSession.sshRemoteId || createWorktreeSession.sessionSshRemoteConfig?.remoteId || undefined;
+
+    // Create the worktree via git (pass SSH remote ID for remote sessions)
    const result = await window.maestro.git.worktreeSetup(
      createWorktreeSession.cwd,
      worktreePath,
-      branchName
+      branchName,
+      sshRemoteId
    );

    if (!result.success) {
@@ -7750,15 +7764,15 @@ function MaestroConsoleInner() {
      saveToHistory: defaultSaveToHistory
    };

-    // Fetch git info for the worktree
+    // Fetch git info for the worktree (pass SSH remote ID for remote sessions)
    let gitBranches: string[] | undefined;
    let gitTags: string[] | undefined;
    let gitRefsCacheTime: number | undefined;

    try {
      [gitBranches, gitTags] = await Promise.all([
-        gitService.getBranches(worktreePath),
-        gitService.getTags(worktreePath)
+        gitService.getBranches(worktreePath, sshRemoteId),
+        gitService.getTags(worktreePath, sshRemoteId)
      ]);
      gitRefsCacheTime = Date.now();
    } catch {
@@ -7808,7 +7822,9 @@ function MaestroConsoleInner() {
      customModel: createWorktreeSession.customModel,
      customContextWindow: createWorktreeSession.customContextWindow,
      nudgeMessage: createWorktreeSession.nudgeMessage,
-      autoRunFolderPath: createWorktreeSession.autoRunFolderPath
+      autoRunFolderPath: createWorktreeSession.autoRunFolderPath,
+      // Inherit SSH configuration from parent session
+      sessionSshRemoteConfig: createWorktreeSession.sessionSshRemoteConfig,
    };

    setSessions(prev => [...prev, worktreeSession]);