Gridwatch

GridWatch 🖥️ A retro-Tron-themed desktop dashboard for monitoring your GitHub Copilot CLI sessions

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.

---

📑 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 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
│   │   ├── 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

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//workspace.yaml | | Prompt history | ~/.copilot/session-state//events.jsonl | | Rewind snapshots | ~/.copilot/session-state//rewind-snapshots/index.json | | Research reports | ~/.copilot/session-state//research/*.md | | Token usage & compaction | ~/.copilot/logs/process--.log | | Copilot skills | ~/.copilot/skills//SKILL.md | | MCP server config | ~/.copilot/mcp-config.json | | LSP server config | ~/.copilot/lsp-config.json | | Custom agent profiles | ~/.copilot/agents/.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// (moved here by GridWatch archive) | | Session tags / custom data | ~/.copilot/session-state//gridwatch.json (tags, notes, plus a tokenStats snapshot so token figures survive Copilot's ~14-day log pruning) | | Skill tags / relationships | ~/.copilot/skills//gridwatch.json (custom tags, childSkills and linkedAgents relationships, plus an orchestration block for orchestrator skills) | | Orchestrator workflow | ~/.copilot/skills//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// (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 req

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BinaryMeadow
• Source: BinaryMeadow/gridwatch
• License: MIT

Install and usage instructions live in the source repository linked above.