# 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

Requires Python 3.10+. Choose the install method that fits your workflow.

Quick Start (Recommended)

    pip install peaky-peek-server && peaky-peek --open

Option 1 — Decorator (Simplest)

    pip install peaky-peek-server

    from agent_debugger_sdk import trace

    @trace
    async def my_agent(prompt: str) -> str:
        return await llm_call(prompt)

Option 2 — Context Manager

    pip install peaky-peek

    from agent_debugger_sdk import trace_session

    async with trace_session("my_agent") as ctx:
        await ctx.record_decision(
            reasoning="User asked for weather",
            confidence=0.9,
            chosen_action="call_weather_api",
        )
        await ctx.record_tool_call("weather_api", {"city": "Seattle"})

Option 3 — Zero-Config Auto-Patch (No Code Changes)

    PEAKY_PEEK_AUTO_PATCH=true python my_agent.py

Works with PydanticAI, LangChain, OpenAI SDK, CrewAI, AutoGen, LlamaIndex, and Anthropic — no imports or decorators needed.

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

Start Debugging on GitHub