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

Peaky Peek Agent Debugger showing decision tree, timeline, and event details

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

Get Started → ★ GitHub
CI PyPI peaky-peek PyPI peaky-peek-server Python 3.10+ License MIT Downloads

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
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
Safety Audit Trail

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

Loop Detection
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.

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