Metadata-Version: 2.4
Name: ai-ctrl-plane
Version: 0.7.0
Summary: AI Control Plane — a local web UI for browsing AI agent session logs and tool configurations (GitHub Copilot, Claude Code, VS Code Chat).
Project-URL: Homepage, https://github.com/l-teles/ai-control-plane
Project-URL: Repository, https://github.com/l-teles/ai-control-plane
Project-URL: Issues, https://github.com/l-teles/ai-control-plane/issues
Author: Luís Teles
License-Expression: MIT
License-File: LICENSE
Keywords: agent,claude,copilot,github,logs,viewer,vscode,vscode-chat
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Flask
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.13
Requires-Dist: flask>=3.0
Requires-Dist: markdown>=3.5
Requires-Dist: markupsafe>=2.1
Requires-Dist: nh3>=0.2.14
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/logo.svg" alt="AI Control Plane logo" width="80">
</p>

<h1 align="center">AI Control Plane</h1>

<p align="center">
  A local web UI for browsing <strong>GitHub Copilot</strong>, <strong>Claude Code</strong>, and <strong>VS Code Chat</strong> agent session logs and tool configurations — all in one place.
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.13%2B-blue" alt="Python 3.13+">
  <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT">
</p>

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.

<table>
  <tr>
    <td align="center"><strong>Dashboard</strong></td>
    <td align="center"><strong>Session Timeline</strong></td>
  </tr>
  <tr>
    <td>
      <a href="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_dark_home.png">
        <picture>
          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_dark_home.png">
          <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_light_home.png">
          <img src="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_dark_home.png" alt="Dashboard homepage" width="400">
        </picture>
      </a>
    </td>
    <td>
      <a href="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_dark_session.png">
        <picture>
          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_dark_session.png">
          <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_light_session.png">
          <img src="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_dark_session.png" alt="Session timeline view" width="400">
        </picture>
      </a>
    </td>
  </tr>
  <tr>
    <td align="center"><strong>Tool Configuration</strong></td>
    <td align="center"><strong>Agents</strong></td>
  </tr>
  <tr>
    <td>
      <a href="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_dark_tools.png">
        <picture>
          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_dark_tools.png">
          <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_light_tools.png">
          <img src="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_dark_tools.png" alt="Tool configuration page" width="400">
        </picture>
      </a>
    </td>
    <td>
      <a href="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_dark_agents.png">
        <picture>
          <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_dark_agents.png">
          <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_light_agents.png">
          <img src="https://raw.githubusercontent.com/l-teles/ai-control-plane/main/assets/screenshot_dark_agents.png" alt="Agents page" width="400">
        </picture>
      </a>
    </td>
  </tr>
</table>


---

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

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

### Install from PyPI

```bash
pip install ai-ctrl-plane
```

### Run

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

```bash
# 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](LICENSE)
