Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/faesel/gridwatch

A Tron-themed desktop app that visualises your GitHub Copilot CLI sessions — browse history, track token usage, and explore activity across all your coding sessions.
https://github.com/faesel/gridwatch

ai ai-agents cli copilot mcp sessions skills

Last synced: 25 days ago
JSON representation

A Tron-themed desktop app that visualises your GitHub Copilot CLI sessions — browse history, track token usage, and explore activity across all your coding sessions.

Awesome Lists containing this project

README 

          


  GridWatch Logo

  
GridWatch


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


  


    Latest Release

    License

    Downloads

  





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)

- [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

- 🔄 **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

- ⬡ **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



![Sessions](public/images/screenshot-sessions.png)



### Tokens



![Tokens](public/images/screenshot-tokens.png)



### Skills



![Skills](public/images/screenshot-skills.png)



### MCP Servers



![MCP Servers](public/images/screenshot-mcp.png)



### LSP Servers



![LSP Servers](public/images/screenshot-lsp.png)



### Agents



![Agents](public/images/screenshot-agents.png)



### Activity



![Activity](public/images/screenshot-activity.png)



### Insights



![Insights](public/images/screenshot-insights.png)



### Transfer



![Transfer](public/images/screenshot-transfer.png)



### Settings



![Settings](public/images/screenshot-settings.png)



### Programs Theme



![Programs Theme](public/images/screenshot-theme.png)



---



## 📋 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

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

│   ├── 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//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`                                                                                                         |

| Skill tags / custom data   | `~/.copilot/skills//gridwatch.json`                                                                                                                |

| 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`                                                                                                                 |

| 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                            |

| 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 */;

```



---



## 🚀 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  --no-git-tag-version

git add package.json package-lock.json

git commit -m "chore: bump version to "

git push origin main

git tag -f v

git push origin v --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)