{"slug": "show-hn-peekai-local-first-observability-for-python-ai-agents", "title": "Show HN: PeekAI – Local-first observability for Python AI agents", "summary": "PeekAI, a new open-source tool for local-first observability and debugging of Python AI agents, launched on Hacker News. The tool stores traces in SQLite, requires no cloud accounts or API keys, and supports multi-agent visualization, trace replay, and CLI/UI inspection. It aims to simplify debugging for developers building AI agents by providing zero-config instrumentation for OpenAI, Anthropic, and LiteLLM.", "body_md": "**Lightweight, local-first observability and debugging for Python AI agents.**\n\nNo cloud. No API keys. No dashboards to sign up for.\n\nDrop it in, call `peekai.init()`\n\n, and see exactly what your agent is doing —\n\nevery LLM call, every tool use, every token spent.\n\nBuilding AI agents is hard. Debugging them is harder. Tools like LangSmith or Weights & Biases require you to send your data to their cloud, create accounts, and wire up pipelines before you can see a single trace.\n\nPeekAI is different:\n\n🏠 Local-first |\nAll traces stored in SQLite at `~/.peekai/peekai.db` — nothing leaves your machine |\n⚡ Zero config |\nOne line to instrument OpenAI, Anthropic, and LiteLLM |\n🧠 Multi-agent aware |\nVisualize agent-to-agent handoffs as a nested span tree |\n🔁 Trace replay |\nRe-run any past trace with a different model or modified tool response |\n🖥️ CLI + UI |\nInspect traces in your terminal or a local Streamlit dashboard |\n\n```\npip install peekai\n\n# With OpenAI support\npip install \"peekai[openai]\"\n\n# With Anthropic support\npip install \"peekai[anthropic]\"\n\n# With the web dashboard\npip install \"peekai[ui]\"\n\n# With everything\npip install \"peekai[all]\"\npython\nimport peekai\nfrom openai import OpenAI\n\n# One line to instrument everything\npeekai.init()\n\nclient = OpenAI()\n\nresponse = client.chat.completions.create(\n    model=\"gpt-4o\",\n    messages=[{\"role\": \"user\", \"content\": \"What is 2 + 2?\"}],\n)\n\nprint(response.choices[0].message.content)\n```\n\nThen inspect your traces:\n\n```\npeekai list                  # recent traces\npeekai view <trace-id>       # full span waterfall\npeekai stats                 # token + cost totals\npeekai ui                    # launch the web dashboard\n```\n\nHow it works—`peekai.init()`\n\nmonkey-patches the SDK clients at startup. No changes to your existing API calls are needed.\n\nDecorate your agents and tools — PeekAI automatically builds the parent/child span tree:\n\n``` python\nimport peekai\nfrom openai import OpenAI\n\npeekai.init()\nclient = OpenAI()\n\n@peekai.agent(\"researcher\")\ndef researcher_agent(topic: str) -> str:\n    response = client.chat.completions.create(\n        model=\"gpt-4o\",\n        messages=[{\"role\": \"user\", \"content\": f\"Research: {topic}\"}],\n    )\n    return response.choices[0].message.content\n\n@peekai.agent(\"writer\")\ndef writer_agent(research: str) -> str:\n    response = client.chat.completions.create(\n        model=\"gpt-4o\",\n        messages=[{\"role\": \"user\", \"content\": f\"Summarise: {research}\"}],\n    )\n    return response.choices[0].message.content\n\n@peekai.tool(\"format_output\")\ndef format_output(text: str) -> str:\n    return f\"📝 {text}\"\n\n@peekai.trace(\"multi_agent_pipeline\")\ndef run():\n    research = researcher_agent(\"the James Webb Space Telescope\")\n    summary = writer_agent(research)\n    return format_output(summary)\n\nrun()\n```\n\nVisualize the agent flow in the terminal:\n\n```\npeekai map <trace-id>\ntrace: multi_agent_pipeline  ✓ ok  3.6s  236 tokens  $0.000222\n\n  └── 🧠 researcher  [agent]  ✓ ok  2.3s\n      └── 🤖 openai/gpt-4o  [llm]  ✓ ok  2.3s  102 tok  $0.000115\n  └── 🧠 writer  [agent]  ✓ ok  1.3s\n      └── 🤖 openai/gpt-4o  [llm]  ✓ ok  1.3s  134 tok  $0.000107\n  └── 🔧 format_output  [tool]  ✓ ok  0ms\n```\n\nRe-run any past trace — swap the model, inject a different tool response, see what would have changed:\n\n```\n# Replay with the same model\npeekai replay <trace-id>\n\n# Swap to a different model\npeekai replay <trace-id> --model gpt-4o\n\n# Swap to Anthropic\npeekai replay <trace-id> --model claude-3-5-sonnet-20241022\n\n# Inject a modified tool response\npeekai replay <trace-id> --tool search=\"different search result\"\n```\n\nThe replay is saved as a new trace and shown side by side in the UI with token/cost deltas.\n\n| Command | Description |\n|---|---|\n`peekai list` |\nShow last 10 traces |\n`peekai view <id>` |\nFull span waterfall with I/O |\n`peekai stats` |\nTotal runs, tokens, cost by model |\n`peekai map <id>` |\nASCII agent flow tree |\n`peekai replay <id>` |\nRe-run a trace (supports `--model` , `--tool` ) |\n`peekai ui` |\nLaunch Streamlit dashboard |\n`peekai clear` |\nWipe local storage |\n\nAll commands accept short trace IDs — the first 8 characters are enough.\n\n```\npeekai ui\n```\n\nOpens at `http://localhost:8501`\n\nwith four pages:\n\n**Dashboard**— KPIs, cost over time, per-model breakdown** Traces**— filterable list with status, tokens, cost** Trace View**— span waterfall with duration bars, input/output tabs, error highlighting** Replay**— run a replay with model swap, side-by-side comparison\n\n| Decorator | What it does |\n|---|---|\n`@peekai.trace(\"name\")` |\nWraps a function as a top-level trace |\n`@peekai.agent(\"name\")` |\nWraps a sub-agent — its LLM calls become children in the tree |\n`@peekai.tool(\"name\")` |\nWraps a tool call as a TOOL span |\n\n```\npeekai.init(\n    db_path=\"./my_traces.db\",  # default: ~/.peekai/peekai.db\n    openai=True,               # patch OpenAI SDK (default True)\n    anthropic=True,            # patch Anthropic SDK (default True)\n    litellm=True,              # patch LiteLLM (default True)\n)\n```\n\nTraces are stored locally at `~/.peekai/peekai.db`\n\nby default. You can open it directly with any SQLite viewer, back it up, or wipe it with `peekai clear`\n\n.\n\n| SDK | Status | Notes |\n|---|---|---|\n| OpenAI | ✅ Auto-patched | sync + async, streaming |\n| Anthropic | ✅ Auto-patched | sync + async, `create(stream=True)` + `stream()` context manager |\n| LiteLLM | ✅ Auto-patched | sync + async |\n\n```\n# Clone and install\ngit clone https://github.com/oussamaKH63/peekai\ncd peekai\nuv sync --extra all  # includes openai, anthropic, litellm, ui\n\n# Run tests\nuv run pytest tests/ -v\n\n# Run the demos\nuv run python examples/demo_agent.py\nuv run python examples/demo_multi_agent.py\n\n# Launch the UI\nuv run peekai ui\n# Install dev dependencies\nuv sync --extra dev\n\n# Run linter\nuv run ruff check src/\n\n# Run type checker\nuv run mypy src/\n\n# Run tests\nuv run pytest tests/ -v\n```\n\nPRs and issues are welcome. See `CONTRIBUTING.md`\n\nfor more detail.\n\nMIT © [Oussema Khorchani](https://github.com/oussamaKH63/peekai)", "url": "https://wpnews.pro/news/show-hn-peekai-local-first-observability-for-python-ai-agents", "canonical_source": "https://github.com/oussamaKH63/peekai", "published_at": "2026-06-21 23:38:15+00:00", "updated_at": "2026-06-21 23:56:11.219233+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "large-language-models", "ai-infrastructure"], "entities": ["PeekAI", "OpenAI", "Anthropic", "LiteLLM", "LangSmith", "Weights & Biases", "SQLite", "Streamlit"], "alternates": {"html": "https://wpnews.pro/news/show-hn-peekai-local-first-observability-for-python-ai-agents", "markdown": "https://wpnews.pro/news/show-hn-peekai-local-first-observability-for-python-ai-agents.md", "text": "https://wpnews.pro/news/show-hn-peekai-local-first-observability-for-python-ai-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-peekai-local-first-observability-for-python-ai-agents.jsonld"}}