ai-ctrl-plane 0.3.1__tar.gz

ai_ctrl_plane-0.3.1/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing / coverage
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Build artifacts
+*.so
+src/ai_ctrl_plane/_version.py
+
+# Environment / secrets
+.env
+.env.*
+
+# Sample session log data (UUID-named directories)
+4e71aaa0-f131-41fd-aeee-8bcaa5efb315/
+8b3c9d7d-60f7-4e4c-a442-eb2ee7ee68e2/
+
+# Old test app
+old_static_app/

ai_ctrl_plane-0.3.1/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.3.0] - 2026-03-15
+
+### Added
+- **"AI Control Plane" rebrand** — new name, dashboard homepage with aggregated
+  metrics (MCP servers, plugins, agents, commands, hooks, feature flags, sessions),
+  tool cards, session breakdown bars, and recent sessions.
+- **Shared base template** — extracted common CSS, navbar, theme toggle, and footer
+  into `base.html`; all pages now extend it via Jinja2 template inheritance.
+- **Dedicated sessions page** (`/sessions`) — full session list with search and
+  source filter buttons, separate from the dashboard.
+- **Tool configuration pages** — `/tools` overview and `/tools/<tool>` detail
+  pages for Claude Code, GitHub Copilot, and VS Code Chat with vertical sidebar
+  navigation and collapsible sections.
+- **Slash commands** — reads and displays Claude Code plugin slash commands
+  (from `commands/*.md` files) with name, plugin, and description.
+- **Feature flags** — now reads GrowthBook cached feature flags in addition to
+  top-level boolean flags from `~/.claude.json`.
+- **Brand SVG icons** — official Claude, GitHub Copilot, and VS Code icons
+  used throughout the UI via Jinja2 macros.
+- **Subagent expandable info** — sub-agent start events show the agent prompt
+  on expand; sub-agent complete events show the result.
+- **Skills page** (`/skills`) — deduplicated list of all installed skills
+  across tools, with source badges and clickable filter pills. Skills with
+  the same name installed in multiple tools are merged into a single card.
+- **Skill detail page** (`/skills/<name>`) — full rendered SKILL.md content
+  with metadata sidebar (author, version, license, tools used, homepage).
+- **Skills data** — reads SKILL.md files (YAML frontmatter + markdown body)
+  for all three tools: Claude Code (standalone + plugin-bundled), GitHub
+  Copilot, and VS Code Chat.
+- **Agents page** (`/agents`) — aggregated view of agents across all tools
+  with clickable source filter pills (Claude / VS Code).
+- **SVG favicon** — inline data URI favicon matching the new logo.
+- **New logo** — slider/mixing console design with three source-colored bars.
+- **GrowthBook flags** — separated from user feature flags in the Claude Code
+  tool detail page, collapsed by default with explanation of what GrowthBook is.
+- **Improved text wrapping** — `overflow-wrap: break-word` applied consistently
+  across tool details, session info, and key-value grids.
+
+### Changed
+- Dashboard homepage now shows tool configs and cross-tool metrics instead of
+  just a session list.
+- All templates refactored to extend `base.html`, removing ~200 lines of
+  duplicated CSS.
+- Tool detail tabs changed from horizontal to vertical sidebar navigation.
+- Policy & Limits section uses single-column layout for readability.
+- Feature Flags section uses compact multi-column grid.
+- Unicode HTML entities (`&#9654;`, `&#10003;`, etc.) replaced with SVG icons
+  throughout session timelines and tool detail pages.
+
+### Fixed
+- Sub-agent count always showing 0 — `compute_stats()` now counts Agent and
+  dispatch_agent tool calls.
+- Sub-agent timeline events now properly emit `subagent_start`/`subagent_complete`
+  instead of generic tool events.
+- VS Code `globalStorage` path resolution — skills and agents now correctly
+  found under the User directory.
+- Claude skills now include plugin-bundled skills (from `plugins/marketplaces/`),
+  not just standalone `~/.claude/skills/`.
+- Agents page navbar highlight — now correctly highlights "Agents" instead of
+  "Tools".
+
+## [0.2.0] - 2026-03-13
+
+### Added
+- **Claude timeline extras** — hook/progress events, file history snapshots,
+  last-prompt markers, permission mode and sidechain indicators on messages.
+- **VS Code timeline extras** — agent mode badges (Edit/Chat/Agent),
+  follow-up suggestion chips, progress task markers, past-tense tool
+  summaries, time-spent-waiting display.
+- **Stats sidebar enhancements** — service tier, cache read/creation token
+  breakdown, prompt token details (stacked bar), cost estimates with
+  multiplier support.
+- **Pending-edits warning** on VS Code session cards in the index.
+
+### Fixed
+
+- Double-slash typo in backup API endpoint path.
+- Tool name parser for Copilot sessions.
+
+## [0.1.0] - 2026-03-12
+
+### Added
+
+- Initial release.
+- Session index page listing all discovered Copilot agent sessions.
+- Session detail view with timeline conversation, statistics sidebar, and
+  rewind snapshots panel.
+- Event type filtering (User, Assistant, Tools, Sub-Agents, Errors).
+- Expandable tool call arguments and results.
+- Expandable assistant reasoning blocks.
+- Markdown rendering for assistant messages.
+- JSON API endpoints (`/api/sessions`, `/api/session/<id>/events`,
+  `//api/session/<id>/backup/<hash>`).
+- CLI entry point (`copilot-log-viewer`) with `--port`, `--host`, and
+  `--debug` options.
+- Security hardening: UUID validation, backup-hash validation, path-traversal
+  protection, Content-Security-Policy, and secure default headers.

ai_ctrl_plane-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luis Teles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_ctrl_plane-0.3.1/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.4
+Name: ai-ctrl-plane
+Version: 0.3.1
+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.
+- **Search & filters** — full-text search across session names, branches, directories,
+  and models; filter by source on the sessions page, by event type in timelines.
+- **Interactive timeline** — color-coded conversation view with:
+  - User messages (with file attachments)
+  - Assistant responses (rendered Markdown, expandable reasoning/thinking)
+  - Tool calls & results (expandable arguments / output)
+  - Sub-agent launches & completions (expandable prompt / result)
+  - System notifications, hooks, file snapshots, model changes
+  - Errors and warnings
+- **Statistics sidebar** — message counts, token usage (input/output/cache),
+  tool breakdown with visual bars, MCP tool usage, rewind snapshots.
+
+### 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 with toggle), settings, policy limits.
+- **GitHub Copilot** — MCP servers, configuration, recent commands, skills.
+- **VS Code Chat** — MCP servers, agents, skills, AI settings, language models.
+- **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)