Peaky Peek — Agent Debugger
Description: Debug AI agents like distributed systems. Capture decisions, tool calls, and LLM interactions as a queryable event timeline.

# See what your agent was thinking.
Fix what went wrong.

The local-first debugger for AI agents. Capture every decision, tool call, and LLM interaction as a queryable event timeline.

Get Started → ★ GitHub

## Why Peaky Peek?

Traditional observability tools weren't built for agent-native debugging.

🏠
Local-first by default

No external telemetry. No SaaS lock-in. Your agent data stays on your machine unless you explicitly configure cloud mode.

🧠
Agent-decision-aware

Captures the causal chain behind every action — reasoning steps, confidence, evidence, and chosen action — not just function calls.

⏪
Interactive replay

Time-travel through any session. Play, pause, step, and seek to any checkpoint. Replay the exact state before a failure occurred.

## Feature Highlights

Everything you need to understand why your agent did what it did.

### Core Debugger

Decision Tree Visualization

Navigate agent reasoning as an interactive tree. Click nodes to inspect events and trace the causal chain from policy to tool call.

Checkpoint Replay

Time-travel through agent execution. Play, pause, step, and seek to any point. Checkpoints ranked by restore value.

Trace Search

Find specific events across all sessions. Search by keyword, filter by event type, and jump directly to results.

### Multi-Agent

Multi-Agent Coordination

Track communication between agents. See handoffs, task delegation, and inter-agent messages in a unified view.

Session Comparison

Compare multiple agent runs side-by-side. Identify where paths diverge and why outcomes differ.

### Safety & Analysis

Safety Audit Trail

Track safety-critical decisions and permission grants. Audit every policy check and intervention point.

Loop Detection

Automatically detect repetitive behavior patterns. Get alerts when agents get stuck in action cycles.

Failure Clustering

Adaptive analysis groups similar failures. Surface highest-severity, highest-novelty events. Click a cluster to focus the timeline.

365+ Tests Passing
8 Framework Adapters
MIT Open Source

### How We Compare

Tool | Focus | Limitation
--- | --- | ---
LangSmith | LLM tracing | SaaS-first, no local-first option
OpenTelemetry | Infra observability | Not agent-decision-aware
Sentry | Error tracking | No reasoning-level insight
Peaky Peek | Agent-native debugging | ✓ Local-first & open source

## Get Started in 2 Steps

Requires Python 3.10+ and a cloned repo. No config files needed to start.

Step 1 — Install

    pip install peaky-peek-server

Step 2 — Run (from repo root after cloning)

    git clone https://github.com/acailic/agent_debugger
    cd agent_debugger
    uvicorn api.main:app --reload --port 8000

API available at `http://localhost:8000` · Full documentation →

Start Debugging on GitHub