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](https://githubnext.com/) 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. --- ## 📑 Table of contents - [Features](#-features) - [Screenshots](#-screenshots) - [Prerequisites](#-prerequisites) - [Installation](#-installation) - [Development](#%EF%B8%8F-development) - [Project structure](#-project-structure) - [Available scripts](#-available-scripts) - [Data sources](#-data-sources) - [Security](#-security) - [Settings](#%EF%B8%8F-settings) - [Tech stack](#%EF%B8%8F-tech-stack) - [Design system](#-design-system) - [Changelog](#-changelog) - [Releasing](#-releasing) - [Contributing](#-contributing) - [License](#-license) - [Author](#-author) --- ## ✨ 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. Token figures are linked to each session via its foreground-session log markers and snapshotted into `gridwatch.json`, so they survive Copilot's ~14-day log pruning; sessions whose logs have been pruned with no saved snapshot are clearly marked as unavailable - 🔄 **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 - ⛓ **Directory-based auto-tag rules** — define rules in Settings that map a directory to one or more tags; any session whose working directory sits under that directory is automatically tagged. Auto-tags are derived at load time (never written to disk), shown read-only with a distinct ⛓ chip, and are searchable and filterable like manual 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 - 🔗 **Skill relationships** — link child skills to a parent skill and link the agents a skill invokes. Child skills are nested under their parent in the list with an expand/collapse accordion and indented, colour-coded markers; nesting is preserved even while filtering. The detail panel shows each skill's child skills, linked agents, and parent skills. Relationship chips are clickable — jump between parent and child skills, or flip to the Agents panel and open a linked agent's detail view - ⌬ **Skills graph** — an interactive relationship map (built with React Flow) of how your skills connect. Pick a parent skill and see it rendered as a node-link diagram: child skills laid out by depth, the agents each skill invokes shown alongside, and colour-coded edges (invokes / uses-agent). Double-click any node to jump straight to that skill or agent. Fully Tron-themed with pan, zoom, and minimap - 🪄 **Orchestrator builder** — switch the skills graph into EDIT mode to compose an orchestrator skill that runs its attached child skills. Create a new orchestrator or new child-skill nodes (with a paste-your-instructions box), attach steps with a searchable combobox or by dragging connections on the canvas, choose **sequential** (one-by-one) or **parallel** (all at once, launched as background tasks) execution, and wire a per-step input/output folder (auto-chained in sequential mode so each step reads the previous step's output). The graph also renders **folder I/O nodes** with labelled read/write edges, parallel steps get a ∥ badge instead of an order number, and a legend with per-kind checkboxes lets you hide/show orchestrators, skills, agents, or folders. Click **Save** to persist the configuration **and** regenerate the runnable workflow into the orchestrator's `SKILL.md` in one action. The generated workflow — which announces each step, names outputs by session id, and consolidates results verbatim — lives in a clearly demarcated GridWatch-managed block (with a `SKILL.md.bak` backup) so your own prose is never clobbered, and a status badge (In sync / Edited / Broken) tells you whether the block still matches the saved configuration. See [`docs/orchestrator-skills/`](docs/orchestrator-skills/) for a worked example - ◈ **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 - ⬡ **LSP server dashboard** — view all configured Language Server Protocol servers from `~/.copilot/lsp-config.json`, enable/disable individual servers, see command details and file extension mappings. Gives you full visibility into the code intelligence available to Copilot CLI - ◎ **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, density, theme, and Copilot CLI configuration management - 🔄 **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  ### Skills Graph  ### MCP Servers  ### LSP 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](https://github.com/faesel/gridwatch/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: ```bash 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 ```bash # 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 │ │ ├── SkillGraphPage.tsx # Skills relationship graph (React Flow) │ │ ├── McpPage.tsx # MCP server dashboard + tool catalogue │ │ ├── LspPage.tsx # LSP server dashboard + enable/disable │ │ ├── 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 │ │ ├── lsp.ts # LspServerData interface │ │ └── global.d.ts # Window.gridwatchAPI type declarations │ ├── lib/ │ │ └── orchestration.ts # Pure orchestrator workflow render/merge/status logic (shared by main + renderer) │ ├── 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 ```bash 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. **Copilot directories (always present):** | 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-snapshots/index.json` | | Research reports | `~/.copilot/session-state/<uuid>/research/*.md` | | Token usage & compaction | `~/.copilot/logs/process-<timestamp>-<pid>.log` | | Copilot skills | `~/.copilot/skills/<name>/SKILL.md` | | MCP server config | `~/.copilot/mcp-config.json` | | LSP server config | `~/.copilot/lsp-config.json` | | Custom agent profiles | `~/.copilot/agents/<name>.agent.md` (read-only — agent profiles with YAML frontmatter) | | Trusted directories | `~/.copilot/config.json` → `trustedFolders` array | **GridWatch-specific files (created and managed by GridWatch):** | Data | Source | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | Archived sessions | `~/.copilot/session-state-archived/<uuid>/` (moved here by GridWatch archive) | | Session tags / custom data | `~/.copilot/session-state/<uuid>/gridwatch.json` (tags, notes, plus a `tokenStats` snapshot so token figures survive Copilot's ~14-day log pruning) | | Skill tags / relationships | `~/.copilot/skills/<name>/gridwatch.json` (custom tags, `childSkills` and `linkedAgents` relationships, plus an `orchestration` block for orchestrator skills) | | Orchestrator workflow | `~/.copilot/skills/<name>/SKILL.md` (a GridWatch-managed block, anchored by `gridwatch:orchestration` markers, is regenerated in place; `SKILL.md.bak` holds the pre-regenerate backup) | | Disabled skills | `~/.copilot/skills-disabled/<name>/` (moved here when toggled off) | | Disabled MCP servers | `~/.copilot/gridwatch-mcp-disabled.json` | | MCP tool cache | `~/.copilot/gridwatch-mcp-tools-cache.json` (cached from JSON-RPC `tools/list` queries) | | Disabled LSP servers | `~/.copilot/gridwatch-lsp-disabled.json` | | Auto-tag rules | `~/.copilot/gridwatch-autotag-rules.json` (directory→tags rules; applied non-destructively at load) | | Encrypted API token | `~/.copilot/gridwatch-token.enc` (encrypted via OS keychain) | **Network requests:** | Request | Endpoint | When | | ------------ | -------------------------------------------------------------- | ---------------- | | Update check | `api.github.com/repos/faesel/gridwatch/releases/latest` | On startup only | ### 🔒 Security - **Context isolation** — renderer process communicates with main only via a typed `gridwatchAPI` bridge; no generic IPC exposed - **Sandbox enabled** — renderer runs in a sandboxed process - **Content Security Policy** — strict CSP applied in production (no inline scripts) - **Input validation** — all IPC handlers validate session IDs (UUID format) and file paths (traversal protection) - **Encrypted secrets** — GitHub PAT encrypted at rest via Electron `safeStorage` (macOS Keychain / Windows DPAPI), scoped to GridWatch's own app identity only - **URL restriction** — `shell.openExternal` limited to HTTP(S) URLs only - **Navigation guards** — `will-navigate` and `setWindowOpenHandler` prevent the Electron window from being redirected to external origins - **Token isolation** — the GitHub PAT never leaves the main process. The renderer only knows whether a token exists (`hasToken`); API calls that require authentication are made entirely within main, keeping the token out of the renderer's JavaScript heap - **Input size limits** — freeform IPC inputs are capped to prevent a renderer bug from writing unbounded data to disk. Session summaries are limited to 1,000 characters, session notes to 100,000 characters, and skill file content to 512KB. Skill filenames are restricted to `.md` extensions only - **HTTP response caps** — outbound HTTP responses (update checks, GitHub Models API) are capped at 1MB. If a response exceeds this limit, the stream is destroyed immediately. This prevents a compromised or misbehaving endpoint from exhausting main process memory - **MCP tool discovery** — GridWatch reads your `~/.copilot/mcp-config.json` and briefly spawns each configured local MCP server to query its tool list via JSON-RPC. GridWatch does not install or modify MCP servers — it only reads what you have already configured. Commands with shell metacharacters are rejected as a safety measure - **Prototype pollution guards** — object property keys sourced from external config (e.g. MCP server names, LSP server names) are validated against known dangerous keys (`__proto__`, `constructor`, `prototype`) and use `hasOwnProperty` checks to prevent prototype chain corruption - **LSP config management** — GridWatch reads and writes `~/.copilot/lsp-config.json` to enable/disable language servers but never spawns or executes LSP server processes. Toggle operations use the same prototype pollution guards and `hasOwnProperty` checks as MCP - **Dev build guard** — packaged builds detect and refuse to run if a Vite dev server URL is present, preventing accidental distribution of builds with a relaxed Content Security Policy - **Hardened runtime** — macOS builds use hardened runtime for notarization compatibility ### ⚙️ Settings The Settings page provides UI preferences and Copilot CLI configuration management, all persisted between launches. **Display preferences** (stored in `localStorage`): | Setting | Description | Options | | --------- | ------------------------------------------------ | ------------------------------------ | | UI Scale | Scales the entire interface via Electron webFrame | XS (80%) – 2XL (135%) | | Font Size | Base text size independent of scale | 10px – 16px | | Density | Padding and spacing between elements | Compact / Default / Comfortable | | Theme | Colour scheme | The Grid (cyan/blue) / Programs (red) | **Copilot CLI configuration** (stored in `~/.copilot/config.json`): | Setting | Description | Config key | | -------------------- | -------------------------------------------------------------------------------- | ---------------- | | Trusted Directories | Directories Copilot CLI can access without the startup trust prompt. Add/remove via folder picker or edit `config.json` directly | `trustedFolders` | **Other:** | Setting | Description | | ---------------------------- | ------------------------------------------------------------------------ | | GitHub Personal Access Token | Required for the Insights tab (GitHub Models API). Encrypted at rest via OS keychain | ### ⚙️ Tech stack | Layer | Technology | | ------------------ | ----------------------------------- | | Framework | Electron | | UI | React 19 + TypeScript | | Build | Vite + vite-plugin-electron | | Packaging | electron-builder | | Styling | CSS Modules + CSS custom properties | | Charts | Recharts | | Graph view | React Flow (@xyflow/react) | | Markdown rendering | marked | | YAML parsing | js-yaml | | Font | JetBrains Mono (@fontsource) | ### 🎨 Design system The Tron-inspired colour palette is defined as CSS custom properties in `src/index.css`: ```css --tron-bg: #060a14 /* near-black background */ --tron-panel: #0a0e1f /* panel/card background */ --tron-cyan: #00f5ff /* primary accent */ --tron-blue: #0080ff /* secondary accent */ --tron-orange: #ff6600 /* destructive / highlight */ --tron-border: #1a2a4a /* border colour */; ``` --- ## 📝 Changelog ### v0.39.5 - **Fixed: main-process crash on large session histories.** The session scan read every `events.jsonl` fully into memory — over 1 GB across a mature `~/.copilot/session-state` tree, with individual files exceeding 80 MB — for all sessions concurrently. This exhausted the V8 heap and killed the app. Session logs are now streamed line by line, with bounded scan concurrency and de-duplication of overlapping scans. - **Much faster refreshes.** Parsed session data is cached against each file's size and modification time, so a refresh only re-reads sessions that actually changed: a warm rescan drops from ~8 s to under 200 ms. - **Snappier UI.** The 30-second poll no longer forces every page to recompute and re-render when nothing has changed, prompt history no longer triggers a layout measurement per message on every render, and hovering the activity heatmap no longer re-renders the charts. Polling also pauses while the window is hidden. - **Faster start-up** — the initial bundle shrank from 717 KB to 226 KB by code-splitting the chart and markdown pages. ### v0.39.4 - **Security: all known dependency vulnerabilities resolved.** `npm audit` now reports zero advisories (previously 16 — 1 critical, 14 high, 1 moderate), covering `tar`, `postcss`, `nanoid`, `brace-expansion`, `js-yaml`, `app-builder-lib` and `extract-zip`. - **Electron upgraded to 41.x**, picking up the latest Chromium security fixes, alongside `electron-builder` 26.15, `marked` 18 and refreshed type packages. - **Lint toolchain modernised** — ESLint 10 with flat config (`eslint.config.js`) and `typescript-eslint` 8. ### v0.39.3 - **Fixed: token metrics restored in the Sessions view.** Copilot CLI ~1.0.70 stopped writing the `Utilization X% (used/total tokens)` lines to its process logs, which caused token panels to disappear. GridWatch now reads token data directly from each session's `events.jsonl`. - **Initial + peak tokens now show up straight away.** Token figures no longer depend on a compaction happening — the startup baseline (`systemTokens + toolDefinitionsTokens`) is used for **initial tokens**, and the session's final `session.shutdown` context occupancy is used for **peak tokens** on sessions that never compacted. Compacted sessions still report the highest pre-compaction peak. - **Smarter context-window inference** from the session model, with the shutdown value correctly excluded from the threshold-based fallback. - **Note:** live/active sessions (not yet compacted or shut down) and very old pre-Feb-2026 sessions have no context-occupancy snapshot in `events.jsonl`, so they show no token panel — an inherent Copilot CLI limitation. --- ## 🚀 Releasing Releases are built and published automatically by GitHub Actions when a version tag is pushed. > **⚠️ Important:** The version in `package.json` determines the artifact filenames (e.g. `GridWatch-Mac-0.22.0-arm64.dmg`). Always bump the version in `package.json` **before** creating the git tag, otherwise the release will produce artifacts with the old version number. ```bash # 1. Bump the version (choose one) npm version patch --no-git-tag-version # 0.5.4 → 0.5.5 (minor changes, bug fixes) npm version minor --no-git-tag-version # 0.5.4 → 0.6.0 (major features, breaking changes) # 2. Commit and push git add package.json package-lock.json git commit -m "chore: bump version to $(node -p "require('./package.json').version")" git push origin main # 3. Tag and push — this triggers the release workflow VERSION=$(node -p "require('./package.json').version") git tag "v$VERSION" && git push origin "v$VERSION" ``` The release workflow will: 1. Create a GitHub Release with auto-generated release notes 2. Build a `.dmg` for macOS (arm64 + x64) in parallel 3. Build an `.exe` NSIS installer for Windows (x64) in parallel 4. Upload both artifacts to the release **If you forget to bump first**, you can fix it by bumping the version, committing, then force-updating the tag: ```bash npm version <correct-version> --no-git-tag-version git add package.json package-lock.json git commit -m "chore: bump version to <correct-version>" git push origin main git tag -f v<correct-version> git push origin v<correct-version> --force ``` > **Note:** The macOS build is currently unsigned. See the [installation section](#macos-app-cannot-be-verified-warning) for the Gatekeeper workaround. --- ## 🤝 Contributing Contributions are welcome! Please read [CONTRIBUTING.md](.github/CONTRIBUTING.md) before submitting a pull request. --- ## 📄 License MIT — see [LICENSE](LICENSE) for details. --- ## 👤 Author **Faesel Saeed** [faesel.com](https://www.faesel.com) · [GitHub](https://github.com/faesel) · [LinkedIn](https://www.linkedin.com/in/faesel-saeed-a97b1614)