Copilot Audit Viewer

A local web app for exploring Copilot chat audit sessions stored in a Git repository.

This project is the viewer dashboard for https://github.com/alxayo/copilot-flight-recorder.

copilot-flight-recorder provides a full audit trail for GitHub Copilot agent sessions. Every prompt, response, and file change is captured and committed linearly to a configurable external Git repository, giving you a complete record you can review, search, or use to reproduce sessions exactly as they happened.

It provides:

• A session dashboard with search
• Session-level timelines (prompts, patches, transcript)
• Cross-reference views that connect audit changes to source files/commits
• Audit + source repository browsing from one UI

The project is built with a React + Vite frontend and an Express + TypeScript backend.

Sample Views

The screenshots below show a few of the main views in the application.

Sessions Dashboard

Session Detail View

Cross-reference view - source explorer

What This Project Solves

When Copilot hooks write session artifacts (for example NNN-prompt.md, NNN-changes.patch, and transcript.json) into an audit repository, it can be hard to inspect those artifacts manually at scale.

This app turns that raw audit data into a navigable interface so you can:

• Review what was asked and changed in each session
• Inspect patch details quickly
• Search across sessions
• Trace audit changes back to a source repository

Architecture

• Frontend: React 19, TypeScript, Vite, React Router, Tailwind CSS
• Backend: Express 4, TypeScript (tsx runtime)
• Git data access: isomorphic-git
• Rendering helpers: react-markdown, diff2html

High-level flow:

1. Backend reads the configured audit/source repositories.
2. Backend exposes data through /api/* endpoints.
3. Frontend fetches from /api/* (proxied by Vite in development).
4. UI renders dashboards, timelines, diffs, and cross-reference views.

Project Structure

AgentAudit/
  server/                  # Express API and git-backed services
    index.ts
    routes/
    services/
  src/                     # React app
    components/
    pages/
    lib/
  spec/                    # Design and planning docs
  .github/hooks/           # Copilot audit hook scripts/config
  package.json
  vite.config.ts

Prerequisites

• Node.js 20+ recommended
• npm 10+ recommended
• Two local Git repositories:
  • Audit repository: contains sessions/<sessionId>/... artifacts
  • Source repository (optional but recommended): codebase used for cross-reference features

Setup Guide

1. Install dependencies

npm install

2. Create environment file

Copy the sample and update paths:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env

3. Configure .env

Set absolute paths for your machine (examples in the sample file):

• COPILOT_AUDIT_REPO: path to audit Git repository
• SOURCE_REPO: path to source Git repository
• PORT: API port (default 3001)

4. Start development mode

npm run dev

This runs:

• Vite frontend at http://localhost:5173
• Express API at http://localhost:3001

5. Open the app

Browse to:

http://localhost:5173

Environment Variables

The backend loads .env from workspace root using dotenv.

Variable	Required	Default	Purpose
PORT	No	3001	Express API port
COPILOT_AUDIT_REPO	Yes (for useful data)	empty	Absolute path to audit Git repo
SOURCE_REPO	No	empty	Absolute path to source Git repo for source/xref pages
COPILOT_AUDIT_MODE	No	flat	Hook mode hint shown in metadata (flat or per-session)
COPILOT_AUDIT_BRANCH	No	main	Hook branch name for flat mode
COPILOT_AUDIT_PUSH	No	false	Hook behavior flag for session-final push

API Overview

Main endpoints exposed by the server:

• GET /api/config - Get current configured repo paths and validity
• POST /api/config - Update repo paths at runtime
• GET /api/sessions - List audit sessions
• GET /api/sessions/:id - Get one session with timeline events
• GET /api/sessions/:id/commits - Get related commits
• GET /api/search?q=... - Search across session artifacts
• GET /api/source/* - Source repository commit/tree/file browsing
• GET /api/xref/* - Cross-reference index and lookups

Available Scripts

From package.json:

• npm run dev:client - Start Vite only
• npm run dev:server - Start API server only (tsx watch server/index.ts)
• npm run dev - Run client + server together
• npm run build - Build frontend assets with Vite

Note:

• The current npm run start script expects dist/server/index.js.
• If you have not produced a server build artifact, use npm run dev:server for local API execution.

Typical Workflow

1. Copilot hooks write audit files into your audit repository.
2. Run the viewer app locally.
3. Point config to your audit/source repos (via .env or the UI config endpoint).
4. Review sessions, prompts, patch history, and transcript events.
5. Use source + xref pages to connect audit changes to source commits/files.

Troubleshooting

• Empty dashboard:

  • Confirm COPILOT_AUDIT_REPO points to a valid Git repo.
  • Confirm the repo has sessions/<sessionId> data.

• Source page errors:

  • Confirm SOURCE_REPO points to a valid Git repo.

• API unreachable:

  • Ensure server is running on PORT (default 3001).
  • Ensure Vite proxy target matches backend port (vite.config.ts).

• Path validation errors in config API:

  • Use absolute paths only.

Related Docs

• spec/plan.md - project plan and architecture notes
• spec/audit-system.md - audit hook system behavior and data format
• .github/hooks/copilot-audit.json - hook event mapping