Panoptes – AI audit and alignment layer

Notifications You must be signed in to change notification settings

Fork 0

Star 3

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

3 Commits

3 Commits

panoptes

panoptes

tests

tests

.gitignore

.gitignore

AGENTS.md

AGENTS.md

LICENSE

LICENSE

README.md

README.md

pyproject.toml

pyproject.toml

test_proxy.py

test_proxy.py

Repository files navigation

Universal agent observability, audit trail, and policy enforcement.

Works with Claude Code, OpenAI Codex, Google Antigravity, and Hermes Agent.

Panoptes watches your AI agents and tells you what they actually did. Recording every tool call, every file read, every shell command, every decision. It captures agent activity across multiple agent frameworks into a single, queryable audit trail, and can also block dangerous actions before they execute via configurable policies.

Named after Panoptes, the all-seeing giant of Greek mythology with a hundred eyes, because your agents need a watcher that never blinks.

Why

Companies are deploying AI coding agents (Claude Code, Codex, Hermes, Antigravity, Cursor) at scale. These agents have access to filesystems, shells, APIs, and production infrastructure. But nobody can answer basic questions like:

"What did the agent actually do yesterday?"

"Did it access production credentials?"

"Which files did it read and modify?"

"How many shell commands did it run?"

Each agent stores its own format — Claude Code JSONL, Codex session files, Hermes hooks, Antigravity nothing. Panoptes normalizes everything into a single, queryable database with a universal schema, a CLI, and a policy engine that can block dangerous operations before they happen.

Quick Start

pip install panoptes

Capture agent activity

Option 1: Start the proxy and route any agent through it

panoptes proxy --port 8081 & HTTP_PROXY=http://localhost:8081 claude-code

Option 2: Hermes plugin (auto-captures every session)

python -m panoptes.install_hermes_plugin

Query what happened

Overview

panoptes status

Find tool calls

panoptes query --agent hermes --event-type tool_call

See a full session timeline

panoptes session

Reconstruct the evidence chain for any event

panoptes evidence

Enforce policies

List active policies

panoptes policy list

Add a policy

panoptes policy add no-prod-access.yaml

Check policies against recent events

panoptes policy check

Architecture

Query & Compliance ← CLI (query, status, session, evidence, policy) Normalization ← schema.py (universal event schema, validation, redaction) Storage ← db.py (SQLite, thread-safe WAL, 7 indices) Capture Adapters ← proxy.py (MITM HTTP proxy) + hermes_plugin.py (Hermes hooks)

Capture adapters

Adapter How it works Coverage

Proxy MITM HTTP proxy intercepting LLM API traffic Any agent that hits an LLM API over HTTP

Hermes Plugin Native Hermes hooks (agent:step, agent:end) Hermes Agent — deepest integration

Universal audit schema

Every event, from every agent, normalized to one format:

{ "event_id": "uuid", "timestamp": "2026-07-04T14:30:00Z", "agent": {"type": "claude_code", "session_id": "abc123"}, "event_type": "tool_call", "action": { "tool_name": "terminal", "parameters": {"command": "kubectl apply -f deploy.yaml"}, "target": "kubectl apply -f deploy.yaml", "data_accessed": ["prod_deploy"] }, "outcome": {"status": "success", "summary": "deployment applied"}, "context": {"turn_number": 12, "user_message": "deploy to prod"}, "cost": {"tokens_in": 800, "tokens_out": 150} }

Policy engine

Policies are YAML files in ~/.panoptes/policies/. Example:

name: "no-prod-access" description: "Block tool calls that access production configs" enabled: true scope: agents: ["hermes", "claude_code", "codex"] rule: event_type: "tool_call" conditions:

• field: "action.data_accessed"

operator: "contains" value: "prod"

• field: "action.tool_name"

operator: "in" value: ["terminal", "write_file", "browser_navigate"] logic: "AND" action: block message: "Production access blocked. Request approval first."

8 condition operators: ==, !=, contains, in, matches (regex), gt, lt, gte, lte

Logic: AND / OR

Scoping: filter by agent type, session ID, event type

Rate limiting: per-session counters (in-memory for v1)

Actions: allow, warn, block

Supported Agents

Agent Capture Method Depth

Claude Code Proxy (HTTP interception) Full API traffic

OpenAI Codex Proxy (HTTP interception) Full API traffic

Google Antigravity Proxy (HTTP interception) Full API traffic

Hermes Agent Native plugin (hooks) Every tool call, turn, and decision

Gemini CLI Proxy Full API traffic

Cursor CLI Proxy Full API traffic

Any HTTP-based agent Proxy Full API traffic

Commands

panoptes proxy Start the MITM audit proxy panoptes status Show event statistics panoptes query Query events (filter by agent, type, tool, time) panoptes session Full session timeline panoptes evidence Decision chain for an event panoptes policy list List loaded policies panoptes policy add Add a policy file panoptes policy check Scan events for violations panoptes policy test Test a policy against a JSON event

Installation

From PyPI (coming soon)

pip install panoptes

From source

git clone https://github.com/miggy-code/Panoptes.git cd Panoptes pip install -e .

Requires Python 3.10+. Zero external dependencies beyond httpx and pyyaml.

Project Status

Panoptes is in active development. Core infrastructure is built and tested:

Phase Status

Proxy capture (HTTP MITM) ✅ Complete

Hermes plugin (native hooks) ✅ Complete

Storage engine (SQLite) ✅ Complete

CLI (9 commands) ✅ Complete

Policy engine (YAML rules) ✅ Complete

Dashboard (web UI) ⏳ Planned

40/40 tests pass.

License

Apache 2.0 — see LICENSE.

Contributing

Panoptes is an open-source contribution to the AI agent infrastructure layer. PRs welcome.

Areas where help is especially valuable:

Additional agent adapters (OTel receiver, MCP tracing)

Dashboard / web UI

Postgres storage backend

Policy packs for compliance frameworks (SOC 2, EU AI Act)

Inspiration

claude-code-trace — Claude Code session viewer

claude-tap — Universal agent proxy

Langfuse — Open-source LLM tracing

Arize Phoenix — Open-source observability

About

AI audit layer

Resources

Readme

License

Apache-2.0 license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks

Report repository

Releases

No releases published

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python 100.0%