{"id":47712311,"url":"https://github.com/acailic/agent_debugger","last_synced_at":"2026-04-02T18:39:56.398Z","repository":{"id":346239412,"uuid":"1187340200","full_name":"acailic/agent_debugger","owner":"acailic","description":"Local-first agent debugger with replay, failure memory, smart    highlights, and drift detection.","archived":false,"fork":false,"pushed_at":"2026-03-31T00:48:54.000Z","size":14129,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-31T01:09:33.445Z","etag":null,"topics":["ai-agents","crewai","debugging","fastapi","langchain","pydantic-ai","python","react","tracing","visualization"],"latest_commit_sha":null,"homepage":"https://acailic.github.io/agent_debugger/peaky-peek-course.html","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acailic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T16:02:36.000Z","updated_at":"2026-03-30T23:00:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/acailic/agent_debugger","commit_stats":null,"previous_names":["acailic/agent_debugger"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/acailic/agent_debugger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acailic%2Fagent_debugger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acailic%2Fagent_debugger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acailic%2Fagent_debugger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acailic%2Fagent_debugger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acailic","download_url":"https://codeload.github.com/acailic/agent_debugger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acailic%2Fagent_debugger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31313139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","crewai","debugging","fastapi","langchain","pydantic-ai","python","react","tracing","visualization"],"created_at":"2026-04-02T18:39:53.630Z","updated_at":"2026-04-02T18:39:56.389Z","avatar_url":"https://github.com/acailic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.jpeg\" alt=\"Peaky Peek\" width=\"128\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eLocal-first agent debugger with replay, failure memory, smart highlights, and drift detection.\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ccode\u003epip install peaky-peek-server \u0026\u0026 peaky-peek --open\u003c/code\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eLocal-first, open-source agent debugger.\u003c/strong\u003e Capture decisions, replay from checkpoints, visualize reasoning trees — all on your machine, no data sent anywhere.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/peaky-peek/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/peaky-peek.svg?label=peaky-peek\" alt=\"PyPI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/peaky-peek-server/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/peaky-peek-server.svg?label=peaky-peek-server\" alt=\"PyPI Server\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.10%2B-blue.svg\" alt=\"Python 3.10+\" /\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-green.svg\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/acailic/agent_debugger/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/acailic/agent_debugger/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/pypi/dm/peaky-peek\" alt=\"Downloads\" /\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./peek-v4-demo.gif\" alt=\"Peaky Peek demo walkthrough\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n## Why Peaky Peek?\n\nTraditional observability tools weren't built for agent-native debugging:\n\n| Tool | Focus | Problem |\n|------|-------|---------|\n| LangSmith | LLM tracing | SaaS-first, your data leaves your machine |\n| OpenTelemetry | Infra metrics | Blind to reasoning chains and decision trees |\n| Sentry | Error tracking | No insight into *why* agents chose specific actions |\n| **Peaky Peek** | **Agent-native debugging** | **Local-first, open source, privacy by default** |\n\nPeaky Peek captures the **causal chain** behind every action so you can debug agents like distributed systems: trace failures, replay from checkpoints, and search across reasoning paths.\n\n---\n\n## Quick Start\n\n### Option 1: Decorator (simplest)\n\n```bash\npip install peaky-peek-server\npeaky-peek --open   # launches API + UI at http://localhost:8000\n```\n\n```python\nfrom agent_debugger_sdk import trace\n\n@trace\nasync def my_agent(prompt: str) -\u003e str:\n    # Your agent logic here — traces are captured automatically\n    return await llm_call(prompt)\n```\n\n### Option 2: Context Manager\n\n```python\nfrom agent_debugger_sdk import trace_session\n\nasync with trace_session(\"weather_agent\") as ctx:\n    await ctx.record_decision(\n        reasoning=\"User asked for weather\",\n        confidence=0.9,\n        chosen_action=\"call_weather_api\",\n        evidence=[{\"source\": \"user_input\", \"content\": \"What's the weather?\"}],\n    )\n    await ctx.record_tool_call(\"weather_api\", {\"city\": \"Seattle\"})\n    await ctx.record_tool_result(\"weather_api\", result={\"temp\": 52, \"forecast\": \"rain\"})\n```\n\n### Option 3: Zero-Config Auto-Patch (no code changes)\n\n```bash\n# Set env var, then run your agent normally\nPEAKY_PEEK_AUTO_PATCH=true python my_agent.py\n```\n\nWorks with **PydanticAI, LangChain, OpenAI SDK, CrewAI, AutoGen, LlamaIndex, and Anthropic** — no imports or decorators needed.\n\n---\n\n## Framework Integrations\n\n### PydanticAI\n\n```python\nfrom pydantic_ai import Agent\nfrom agent_debugger_sdk import init\nfrom agent_debugger_sdk.adapters import PydanticAIAdapter\n\ninit()\n\nagent = Agent(\"openai:gpt-4o\")\nadapter = PydanticAIAdapter(agent, agent_name=\"support_agent\")\n```\n\n### LangChain\n\n```python\nfrom agent_debugger_sdk import init\nfrom agent_debugger_sdk.adapters import LangChainTracingHandler\n\ninit()\n\nhandler = LangChainTracingHandler(session_id=\"my-session\")\n# Pass handler to your LangChain agent's callbacks\n```\n\n### OpenAI SDK\n\nNo code needed — just set the environment variable:\n\n```bash\nPEAKY_PEEK_AUTO_PATCH=true python my_openai_agent.py\n```\n\nOr use the simplified decorator:\n\n```python\nfrom agent_debugger_sdk import trace\n\n@trace(name=\"openai_agent\", framework=\"openai\")\nasync def my_agent(prompt: str) -\u003e str:\n    client = openai.AsyncOpenAI()\n    response = await client.chat.completions.create(\n        model=\"gpt-4o\", messages=[{\"role\": \"user\", \"content\": prompt}]\n    )\n    return response.choices[0].message.content\n```\n\n### Auto-Patch (Any Framework)\n\n```python\nimport agent_debugger_sdk.auto_patch  # activates on import when PEAKY_PEEK_AUTO_PATCH is set\n\n# Now run your agent normally — all LLM calls are traced automatically\n```\n\n---\n\n## Features\n\n### Decision Tree Visualization\n\n\u003cp\u003e\n  \u003cimg src=\"./docs/screenshots/gif-decision-tree.gif\" alt=\"Decision Tree visualization demo\" width=\"720\" /\u003e\n\u003c/p\u003e\n\nNavigate agent reasoning as an interactive tree. Click nodes to inspect events, zoom to explore complex flows, and trace the causal chain from policy to tool call to safety check.\n\n### Checkpoint Replay\n\n\u003cp\u003e\n  \u003cimg src=\"./docs/screenshots/gif-checkpoint-replay.gif\" alt=\"Checkpoint replay demo\" width=\"720\" /\u003e\n\u003c/p\u003e\n\nTime-travel through agent execution with checkpoint-aware playback. Play, pause, step, and seek to any point in the trace. Checkpoints are ranked by restore value so you jump to the most useful state.\n\n### Trace Search\n\nFind specific events across all sessions. Search by keyword, filter by event type, and jump directly to results.\n\n### Failure Clustering \u0026 Multi-Agent Coordination\n\n\u003cp\u003e\n  \u003cimg src=\"./docs/screenshots/gif-failure-clustering.gif\" alt=\"Failure clustering demo\" width=\"720\" /\u003e\n\u003c/p\u003e\n\u003cp\u003e\n  \u003cimg src=\"./docs/screenshots/gif-multi-agent-coordination.gif\" alt=\"Multi-agent coordination demo\" width=\"720\" /\u003e\n\u003c/p\u003e\n\nAdaptive analysis groups similar failures. Inspect planner/critic debates, speaker topology, and prompt policy parameters across multi-agent systems.\n\n### Session Comparison\n\nCompare two agent runs side-by-side. See diffs in turn count, speaker topology, policies, stance shifts, and grounded decisions.\n\n---\n\n## Privacy \u0026 Security\n\n- **Local-first by default** — no external telemetry, no data leaves your machine\n- **Zero-config auto-patching** — no credentials or API keys needed for local debugging\n- **Optional redaction pipeline** — prompts, payloads, PII regex\n- **API key authentication** — bcrypt hashing\n- **GDPR/HIPAA friendly** — SQLite storage, no cloud dependency\n\n## Deployment\n\n### pip (recommended)\n\n```bash\npip install peaky-peek-server\npeaky-peek --open\n```\n\n### Docker\n\n```bash\ndocker build -t peaky-peek .\ndocker run -p 8000:8000 -v ./traces:/app/traces peaky-peek\n```\n\n### Development\n\n```bash\ngit clone https://github.com/acailic/agent_debugger\ncd agent_debugger\npip install -e \".[dev]\"\npip install fastapi \"uvicorn[standard]\" \"sqlalchemy[asyncio]\" aiosqlite alembic aiofiles bcrypt\npython3 -m pytest -q\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run build\n```\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TB\n    subgraph SDK[\"SDK Layer\"]\n        direction LR\n        DEC[\"@trace decorator\"]\n        CTX[\"trace_session()\"]\n        AP[\"Auto-Patch\"]\n        AD[\"Framework Adapters\"]\n    end\n\n    subgraph API[\"API Layer — FastAPI\"]\n        direction LR\n        R1[\"Sessions\"]\n        R2[\"Traces\"]\n        R3[\"Replay\"]\n        R4[\"Search\"]\n        R5[\"Analytics\"]\n        SSE[\"SSE Stream\"]\n    end\n\n    subgraph STORE[\"Storage Layer\"]\n        direction LR\n        S1[\"Sessions\"]\n        S2[\"Events\"]\n        S3[\"Checkpoints\"]\n        S4[\"Snapshots\"]\n    end\n\n    subgraph UI[\"Frontend — React + TypeScript\"]\n        direction LR\n        DT[\"Decision Tree\"]\n        TI[\"Tool Inspector\"]\n        SR[\"Session Replay\"]\n        FC[\"Failure Clustering\"]\n        MA[\"Multi-Agent View\"]\n    end\n\n    SDK -- \"HTTP / WebSocket\" --\u003e API\n    API -- \"SQLite / PostgreSQL\" --\u003e STORE\n    UI -- \"REST + SSE\" --\u003e API\n```\n\nSee [ARCHITECTURE.md](./ARCHITECTURE.md) for full module breakdown.\n\n---\n\n## Project Status\n\n- **Core debugger** — local path end-to-end, stable\n- **SDK** — `@trace`, `trace_session()`, auto-patch for 7 frameworks\n- **API** — 11 routers: sessions, traces, replay, search, analytics, cost, comparison\n- **Frontend** — 8 specialized panels (decision tree, replay, checkpoints, search)\n- **Tests** — 365+ passing, CI on Python 3.10/3.11/3.12\n\n---\n\n## Scientific Foundations\n\nPeaky Peek is informed by research on agent debugging, causal tracing, failure analysis, and adaptive replay. See [paper notes](./docs/papers/README.md) for design takeaways from each.\n\n- [AgentTrace: Causal Graph Tracing for Root Cause Analysis](./docs/papers/agenttrace-causal-graph-tracing-for-root-cause-analysis.md)\n- [XAI for Coding Agent Failures](./docs/papers/xai-for-coding-agent-failures.md)\n- [FailureMem: Failure-Aware Autonomous Software Repair](./docs/papers/failuremem-failure-aware-autonomous-software-repair.md)\n- [MSSR: Memory-Aware Adaptive Replay](./docs/papers/mssr-memory-aware-adaptive-replay.md)\n- [Learning When to Act or Refuse](./docs/papers/learning-when-to-act-or-refuse.md)\n- [Policy-Parameterized Prompts](./docs/papers/policy-parameterized-prompts.md)\n- [CXReasonAgent: Evidence-Grounded Diagnostic Reasoning](./docs/papers/cxreasonagent-evidence-grounded-diagnostic-reasoning.md)\n- [NeuroSkill: Proactive Real-Time Agentic System](./docs/papers/neuroskill-proactive-real-time-agentic-system.md)\n- [REST: Receding Horizon Explorative Steiner Tree](./docs/papers/rest-receding-horizon-explorative-steiner-tree.md)\n- [Towards a Neural Debugger for Python](./docs/papers/towards-a-neural-debugger-for-python.md)\n\n## Documentation\n\n- [5-Minute Getting Started](./docs/getting-started.md)\n- [Integration Guide](./docs/integration.md)\n- [SDK README](./SDK_README.md)\n- [Architecture Overview](./ARCHITECTURE.md)\n- [Progress Tracker](./docs/progress.md)\n\n---\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facailic%2Fagent_debugger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facailic%2Fagent_debugger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facailic%2Fagent_debugger/lists"}