# 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. - **Type:** MCP server - **Install:** `agentstack add mcp-binarymeadow-gridwatch` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [BinaryMeadow](https://agentstack.voostack.com/s/binarymeadow) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [BinaryMeadow](https://github.com/BinaryMeadow) - **Source:** https://github.com/BinaryMeadow/gridwatch ## Install ```sh agentstack add mcp-binarymeadow-gridwatch ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About 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](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//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](https://github.com/BinaryMeadow) - **Source:** [BinaryMeadow/gridwatch](https://github.com/BinaryMeadow/gridwatch) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** no - **Filesystem access:** yes - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: passed β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-binarymeadow-gridwatch - Seller: https://agentstack.voostack.com/s/binarymeadow - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.