PeekAI, a new open-source observability library for Python AI agents, just dropped on Hacker News with a pitch that should make privacy-conscious developers pay attention: zero cloud dependency, no API key handshakes, and full trace visibility with a single function call.
The Privacy-First Approach The core differentiator here is straightforward — all traces live in SQLite at ~/.peekai/peekai.db. Nothing gets sent to external servers. While platforms like LangSmith and Weights & Biases require account creation and pipeline wiring before you see your first trace, PeekAI asks for none of that. Just pip install, call peekai.init(), and you're watching every LLM invocation, tool execution, and token counter in real time.
Monkey-Patch Magic The library works by monkey-patching SDK clients at startup — no modifications to existing API calls required. Currently supported are OpenAI (sync + async, streaming), Anthropic (including create(stream=True) and stream() context managers), and LiteLLM across both sync and async patterns. The @peekai.agent(), @peekai.tool(), and @peekai.trace() decorators let you build out a parent/child span tree that visualizes agent-to-agent handoffs as nested relationships.
Trace Replay: A Developer Dream The trace replay feature is where things get interesting for debugging workflows. Any past trace can be re-run with different parameters — swap the model (say, from GPT-4o to Claude 3.5 Sonnet), inject modified tool responses, or both. The system saves replays as new traces and displays side-by-side comparisons in the UI with token and cost deltas. For iterative agent development, this is genuinely useful.
CLI and Web Dashboard Options Developers can inspect traces through two paths: a terminal-first CLI (peekai list, peekai view , peekai stats, peekai map ) or a local Streamlit dashboard at http://localhost:8501. The web UI offers four pages covering KPIs with cost-over-time trends, filterable trace lists, span waterfalls with input/output tabs and error highlighting, and the replay comparison interface.
Development Setup The project uses uv for dependency management with extras supporting all dependencies (openai, anthropic, litellm, ui). Tests run via pytest, linting through ruff, and type checking through mypy. MIT licensed by author Oussema Khorchani, with PRs and issues welcome on GitHub.
Key Takeaways
- Single-line instrumentation via peekai.init() — no SDK code changes needed
- All data stays local in SQLite — privacy-preserving by design
- Multi-agent span trees visualize complex agent pipelines
- Trace replay supports model swapping and tool response injection
- Supports OpenAI, Anthropic, and LiteLLM with sync/async and streaming