Gridwatch

<div align="center"> <img src="build/icon.png" alt="GridWatch Logo" width="180" /> <h1>GridWatch</h1> <p><strong>🖥️ A retro-Tron-themed desktop dashboard for monitoring your GitHub Copilot CLI sessions</strong></p> <p> <a href="https://github.com/faesel/gridwatch/releases/latest"><img src="https://img.shields.io/github/v/release/faesel/gridwatch?style=flat-square&color=00f5ff" alt="Latest Release" /></a> <a href="https://github.com/faesel/gridwatch/blob/main/LICENSE"><img src="https://img.shields.io/github/license/faesel/gridwatch?style=flat-square&color=0080ff" alt="License" /></a> <a href="https://github.com/faesel/gridwatch/releases"><img src="https://img.shields.io/github/downloads/faesel/gridwatch/total?style=flat-square&color=ff6600" alt="Downloads" /></a> </p> </div>

GridWatch reads the local session data written by GitHub Copilot CLI to ~/.copilot/session-state/ and presents it as a beautiful, real-time dashboard — giving you visibility into your AI-assisted workflow across every project you work on.

---

✨ Features

• 📋 Sessions overview — browse all Copilot CLI sessions with live status, token utilisation, and last prompt
• 🔍 Search & filtering — full-text search, multi-select tag filtering, and session type filter (All / Research / Review / Coding)
• 🔬 Session type detection — automatically identifies research sessions (RESEARCH badge) and code review sessions (REVIEW badge, purple) by detecting Copilot's code-review agent usage
• 📄 Pagination — sessions list paged at 20 per page for fast loading
• 💬 Prompt history — read every user message from a session's events.jsonl directly in the UI
• 📈 Token usage graphs — line charts tracking peak context window usage over time with 1D / 1W / 1M / ALL time range filters
• 🔄 Compaction tracking — detects when Copilot compacts the conversation context, showing trigger utilisation, messages replaced, tokens saved, and the compacted summary. Expandable checkpoint viewer lets you read the full checkpoint markdown inline
• 📝 Research reports — surfaces markdown reports generated by Copilot's research agent with open-in-folder buttons
• 🟩 Activity heatmap — GitHub-style contribution grid showing your session activity over 52 weeks
• ⚡ AI Insights — analyse your sessions with OpenAI to get prompt quality scores and improvement suggestions
• 🏷️ Tagging — add, remove, and filter sessions by custom tags
• ✦ Skills management — browse, create, edit, duplicate, delete, and search your Copilot CLI skills (~/.copilot/skills/). View rendered markdown with Tron-themed styling, toggle skills on/off, rename folders, import from files or folders, and export as zip archives. Tag skills with custom labels and filter by tags
• ◈ MCP server dashboard — view all installed Model Context Protocol servers (local stdio and remote HTTP), enable/disable servers to manage context window bloat, browse their full tool catalogues grouped by category with descriptions and parameter schemas (queried live via JSON-RPC tools/list), see environment variables (with secret masking), connection times, and command details
• ◎ Agents panel — view built-in Copilot agents (Research, Code Review, Coding) alongside your custom agents from ~/.copilot/agents/. See session counts, usage stats, and linked session history per agent. Custom agents display with an orange CUSTOM badge, rendered markdown file viewer with Tron-themed styling, and file tabs for multi-file agents. Session lists default to the 5 most recent with a "show all" toggle for performance
• ✏️ Rename sessions — give sessions a meaningful name beyond the auto-generated summary
• 🗑️ Archive / Delete — safely archive or permanently remove old sessions (guards against deleting active sessions)
• 📂 Open in folder — reveal research reports and modified files in Finder (macOS) or Explorer (Windows)
• 🔔 Update notifications — automatically checks GitHub Releases for new versions and shows a download banner
• ⚙️ Settings — adjustable UI scale, font size, and density presets, persisted between launches
• 🔄 Auto-refresh — dashboard refreshes every 30 seconds automatically
• 🎨 Retro Tron theme — neon cyan, electric blue, and orange accents on near-black backgrounds with JetBrains Mono typography

---

📸 Screenshots

Sessions

Tokens

Skills

MCP Servers

Agents

Activity

Insights

Transfer

Settings

Programs Theme

---

📋 Prerequisites

| Requirement | Version | | ------------------ | ------------------------------------------------------ | | Node.js | 18+ | | npm | 9+ | | GitHub Copilot CLI | Any version that writes to ~/.copilot/session-state/ | | macOS / Windows | 10+ |

---

📥 Installation

💾 Download a release

Visit the Releases page and download the installer for your platform:

• macOS — .dmg (arm64 or x64)
• Windows — .exe (NSIS installer)

🍎 macOS: "app cannot be verified" warning

The app is not code-signed, so macOS Gatekeeper will block it on first launch. After dragging GridWatch to Applications, run:

xattr -cr /Applications/GridWatch.app

Then open GridWatch as normal. You only need to do this once.

🔑 macOS: Keychain access prompt

On first launch, macOS may ask you to allow GridWatch to access its own keychain entry. This is used only to encrypt your GitHub Personal Access Token (if you add one for AI Insights). GridWatch does not read or access any other keychain items — the access is scoped exclusively to its own encryption key (com.faesel.gridwatch). You can safely click Allow or Always Allow.

Windows users: No equivalent prompt appears. Windows uses DPAPI (Data Protection API) which encrypts data transparently under your Windows user account — no additional permissions are needed.

🔧 Build from source

# Clone the repository
git clone https://github.com/faesel/gridwatch.git
cd gridwatch

# Install dependencies
npm install

# Start in development mode
npm run dev

---

🛠️ Development

📁 Project structure

gridwatch/
├── electron/
│   ├── main.ts          # Main process — window creation, all IPC handlers
│   └── preload.ts       # Context bridge — exposes gridwatchAPI to renderer
├── src/
│   ├── pages/
│   │   ├── SessionsPage.tsx    # Sessions list + detail panel
│   │   ├── TokensPage.tsx      # Token usage charts
│   │   ├── ActivityPage.tsx    # Heatmap + activity analytics
│   │   ├── SkillsPage.tsx      # Copilot skills browser and editor
│   │   ├── McpPage.tsx         # MCP server dashboard + tool catalogue
│   │   ├── AgentsPage.tsx      # Built-in + custom agents with session linking
│   │   ├── InsightsPage.tsx    # AI-powered prompt feedback
│   │   ├── TransferPage.tsx    # Session context transfer
│   │   └── SettingsPage.tsx    # UI scale / font / density controls
│   ├── types/
│   │   ├── session.ts          # SessionData and related interfaces
│   │   ├── skill.ts            # SkillData and SkillFile interfaces
│   │   ├── agent.ts            # CustomAgentData interface
│   │   ├── mcp.ts              # McpServerData and McpEnvVar interfaces
│   │   └── global.d.ts         # Window.gridwatchAPI type declarations
│   ├── App.tsx                 # Shell layout, sidebar nav, auto-refresh
│   └── index.css               # Global styles + Tron design system variables
├── public/
│   └── icon.png                # App icon (1024x1024)
└── build/
    └── icon.png                # electron-builder icon source

📜 Available scripts

npm run dev          # Start development server with hot reload
npm run dev:debug    # Start with DevTools open (useful for debugging)
npm run build        # Type-check and build (clean first)
npm run clean        # Remove dist and dist-electron directories
npm run lint         # Run ESLint across the project
npm run pack:mac     # Build and package for macOS (creates .dmg files)
npm run pack:win     # Build and package for Windows (creates .exe installer)
npm run pack:all     # Build for all platforms

📊 Data sources

GridWatch reads exclusively from local files — no network requests are made except to check for updates and (optionally) to call the GitHub Models API for AI Insights.

| Data | Source | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Session metadata | ~/.copilot/session-state/<uuid>/workspace.yaml | | Prompt history | ~/.copilot/session-state/<uuid>/events.jsonl | | Rewind snapshots | `~/.copilot/session-state/<uuid>/rewind-s