ai-ctrl-plane 0.7.0

AI Control Plane — a local web UI for browsing AI agent session logs and tool configurations (GitHub Copilot, Claude Code, VS Code Chat).

AI Control Plane

A local web UI for browsing GitHub Copilot, Claude Code, and VS Code Chat agent session logs and tool configurations — all in one place.

AI coding agents produce rich session logs and configuration files. This tool turns those raw files into a readable, interactive dashboard so you can review sessions (prompts, reasoning, tool calls, sub-agents, errors) and inspect tool configurations (MCP servers, plugins, agents, skills, slash commands, hooks, feature flags) — all in one place.

Dashboard	Session Timeline
Tool Configuration	Agents

---

Features

Dashboard & Navigation

• Metrics dashboard — aggregated counts for MCP servers, plugins, agents, slash commands, hooks, feature flags, and sessions across all tools.
• Tool cards — at-a-glance status for Claude Code, GitHub Copilot, and VS Code Chat with key stats per tool.
• Shared navbar — sticky navigation with brand SVG icons, breadcrumbs, and dark/light theme toggle.

Session Browser

• Multi-source support — browse sessions from GitHub Copilot, Claude Code, and VS Code Chat side by side, with color-coded source badges.
• Full-text search — SQLite FTS5 indexes the full conversation content (user prompts, assistant responses, thinking blocks, tool results) plus summary, cwd, and model. Live as you type; press Enter for a URL-shareable view. Punctuation that confuses FTS (hyphens, quotes, parens) is auto-sanitised.
• Date-range filter — natural language (yesterday, last week, 3 days ago, 2026-04-01) on top of the sessions list.
• Filters — by source (Claude / Copilot / VS Code) and by event type inside the timeline (user / assistant / tools / sub-agents / notifications / errors). Per-source counts update live as the search narrows.
• Session minimap — clickable timeline overview at the top of each session, one coloured tick per event. Click to scroll the timeline to that point.
• Interactive timeline — DAG-ordered (resumed-session branches render with each child immediately following its parent) with per-tool layouts:
  • Bash with ANSI colour rendering
  • Read / Write / Edit with file path and side-by-side red/green diff
  • Grep / Glob with pattern + match list
  • WebFetch / WebSearch with clickable URLs and structured result cards
  • AskUserQuestion with question + options + answer
  • TodoWrite with status-coloured checkbox list
  • Slash commands (/init, /clear, …) as structured cards with command-name, args, stdout, stderr fields
  • User messages, assistant responses (rendered Markdown, expandable thinking)
  • Inline subagent transcripts (Claude Code 2.1.2+ subagents/ directory)
  • Sub-agent launches & completions, file snapshots, model changes
  • Errors, warnings, hooks, system notifications
  • Inline image rendering for base64 image blocks in tool results
• Statistics sidebar — message counts, token usage (input/output/cache), tool breakdown with visual bars, MCP tool usage, rewind snapshots, memory file count, repo-local permission summary.
• Resume command — Claude session sidebar has a one-click button that copies claude -r <session_id> to the clipboard.

Cache

• Incremental refresh on every launch — new sessions appear automatically; no need to click "Rebuild cache" after every conversation. Each session records its source-file mtime; only modified files are re-parsed, deleted files are dropped.
• Schema migrations — versioned SQL files in migrations/ keep older caches upgradable in place rather than wiped on every schema change.

Tool Configuration Inspector

• Claude Code — MCP servers, plugins (official + external), agents, skills (standalone + plugin-bundled), slash commands, hooks, feature flags (including GrowthBook server-side flags), settings, policy limits, global memory files, remote settings, usage stats, enterprise managed settings (macOS, Linux/WSL, Windows via MDM/ADMX), MCP auth cache, plugin marketplaces & install counts.
• GitHub Copilot — MCP servers, configuration, recent commands, skills.
• VS Code Chat — MCP servers, agents, skills, AI settings, language models; VS Code Insiders sessions and config auto-discovered alongside Stable.
• Vertical tool navigation — switch between tools from the sidebar.

Agents

• Aggregated agents page — view all agents across Claude Code and VS Code in one place.
• Clickable source filters — filter agents by tool (Claude / VS Code) with pill-style toggle buttons.

Skills

• Skills browser (/skills) — deduplicated list of all installed skills across Claude Code, GitHub Copilot, and VS Code Chat, with source badges showing which tools each skill is installed in.
• Skill detail page (/skills/<name>) — full rendered SKILL.md content with metadata sidebar (author, version, license, tools, homepage).

General

• Dark / Light mode — toggle with one click; persisted in localStorage.
• JSON API — programmatic access at /api/sessions, /api/session/<id>/events, /api/tools, and /api/tools/<tool>.
• Security — UUID & backup-hash validation, path-traversal protection, Content-Security-Policy headers, localhost-only by default.

Quick start

Install from source

git clone https://github.com/l-teles/ai-control-plane.git
cd ai-control-plane
pip install .

Install from PyPI

pip install ai-ctrl-plane

Run

# Auto-detect default directories for all sources
ai-ctrl-plane

# Specify directories explicitly
ai-ctrl-plane --copilot-dir ~/.copilot/session-state/ --claude-dir ~/.claude/projects/ --vscode-dir "~/Library/Application Support/Code/User/"

# Or use the module directly
python -m ai_ctrl_plane

Then open http://127.0.0.1:5000 in your browser.

Default directories

Source	macOS / Linux default	Windows default	Override flag	Env variable
GitHub Copilot	~/.copilot/session-state/	%LOCALAPPDATA%\github-copilot\session-state	--copilot-dir	COPILOT_LOG_DIR
Claude Code	~/.claude/projects/	%LOCALAPPDATA%\claude\projects	--claude-dir	CLAUDE_LOG_DIR
VS Code Chat	~/Library/Application Support/Code/User/ (macOS) / ~/.config/Code/User/ (Linux)	%APPDATA%\Code\User	--vscode-dir	VSCODE_LOG_DIR

Options

usage: ai-ctrl-plane [-h] [--copilot-dir DIR] [--claude-dir DIR]
                             [--vscode-dir DIR] [-p PORT] [--host HOST]
                          [--debug] [-V] [log_dir]

positional arguments:
  log_dir               Directory containing Copilot session log folders
                        (default: ~/.copilot/session-state/)

options:
  --copilot-dir DIR     Directory containing Copilot session log folders
                        (overrides positional arg)
  --claude-dir DIR      Directory containing Claude Code session logs
                        (default: ~/.claude/projects/)
  --vscode-dir DIR      Directory containing VS Code Chat session logs
                        (default: platform-dependent)
  -p, --port PORT       Port to listen on (default: 5000)
  --host HOST           Host to bind to (default: 127.0.0.1)
  --debug               Run in Flask debug mode (local development only)
  -V, --version         Show version and exit

Expected directory layouts

GitHub Copilot (~/.copilot/session-state/)

session-state/
├── 4e71aaa0-f131-41fd-aeee-8bcaa5efb315/
│   ├── workspace.yaml          # Session metadata
│   ├── events.jsonl            # Conversation event stream
│   ├── checkpoints/
│   │   └── index.md
│   └── rewind-snapshots/
│       ├── index.json          # Snapshot manifest
│       └── backups/            # File content snapshots
│           ├── ff627b50b0554488-1773312027139
│           └── ...
├── 8b3c9d7d-60f7-4e4c-a442-eb2ee7ee68e2/
│   └── ...
└── ...

Claude Code (~/.claude/projects/)

projects/
├── -Users-you-project-alpha/
│   ├── a1b2c3d4-e5f6-7890-abcd-ef1234567890.jsonl
│   ├── d4c3b2a1-f6e5-0987-dcba-0987654321fe.jsonl
│   └── ...
├── -Users-you-project-beta/
│   └── ...
└── ...

Each .jsonl file is a single session containing user/assistant/system events with tool calls, thinking blocks, and usage metadata.

VS Code Chat (~/Library/Application Support/Code/User/)

User/
├── workspaceStorage/
│   ├── abc123hash/
│   │   ├── workspace.json            # Maps to project folder
│   │   └── chatSessions/
│   │       ├── 88ca1adb-bf72-4478-9982-6886cb99785e.json
│   │       └── ...
│   └── ...
└── globalStorage/
    └── emptyWindowChatSessions/
        ├── 3a9ae123-2cbe-4c1d-b5af-3d4cd1f0ad2e.jsonl
        └── ...

Each .json file is a single chat session with user messages, assistant responses, tool call rounds, and timing metadata.

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Lint
ruff check src/ tests/

# Test
pytest

Security

• Localhost only — binds to 127.0.0.1 by default; never expose to the public internet without authentication.
• Input validation — session IDs must be valid UUIDs; backup hashes are validated against a strict pattern.
• Path-traversal protection — resolved file paths are verified via Path.relative_to() to stay within the configured log directory.
• HTML sanitization — Markdown output is sanitized to strip dangerous tags (<script>, <iframe>, etc.) and event handler attributes.
• Security headers — X-Content-Type-Options, X-Frame-Options, Referrer-Policy, and Content-Security-Policy are set on every response.
• No debug in production — debug mode is off by default and must be explicitly enabled via --debug.
• Dependency monitoring — Dependabot is configured for automated security updates.

License

MIT