Show HN: PeekAI – Local-first observability for Python AI agents

Notifications You must be signed in to change notification settings

Fork 1

Star 1

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

24 Commits

24 Commits

.github/workflows

.github/workflows

.streamlit

.streamlit

examples

examples

src/peekai

src/peekai

tests

tests

.env.example

.env.example

.gitignore

.gitignore

CHANGELOG.md

CHANGELOG.md

CONTRIBUTING.md

CONTRIBUTING.md

LICENSE

LICENSE

README.md

README.md

peekai-name-logo.png

peekai-name-logo.png

pyproject.toml

pyproject.toml

uv.lock

uv.lock

Repository files navigation

Why PeekAI?

Building 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.

PeekAI is different:

🏠 Local-first All traces stored in SQLite at ~/.peekai/peekai.db — nothing leaves your machine

⚡ Zero config One line to instrument OpenAI, Anthropic, and LiteLLM

🧠 Multi-agent aware Visualize agent-to-agent handoffs as a nested span tree

🔁 Trace replay Re-run any past trace with a different model or modified tool response

🖥️ CLI + UI Inspect traces in your terminal or a local Streamlit dashboard

Install

pip install peekai

With OpenAI support

pip install "peekai[openai]"

With Anthropic support

pip install "peekai[anthropic]"

With the web dashboard

pip install "peekai[ui]"

With everything

pip install "peekai[all]"

Quickstart

import peekai from openai import OpenAI

One line to instrument everything

peekai.init()

client = OpenAI()

response = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": "What is 2 + 2?"}], )

print(response.choices[0].message.content)

Then inspect your traces:

peekai list # recent traces peekai view # full span waterfall peekai stats # token + cost totals peekai ui # launch the web dashboard

How it works — peekai.init() monkey-patches the SDK clients at startup. No changes to your existing API calls are needed.

Multi-Agent Support

Decorate your agents and tools — PeekAI automatically builds the parent/child span tree:

import peekai from openai import OpenAI

peekai.init() client = OpenAI()

@peekai.agent("researcher") def researcher_agent(topic: str) -> str: response = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": f"Research: {topic}"}], ) return response.choices[0].message.content

@peekai.agent("writer") def writer_agent(research: str) -> str: response = client.chat.completions.create( model="gpt-4o", messages=[{"role": "user", "content": f"Summarise: {research}"}], ) return response.choices[0].message.content

@peekai.tool("format_output") def format_output(text: str) -> str: return f"📝 {text}"

@peekai.trace("multi_agent_pipeline") def run(): research = researcher_agent("the James Webb Space Telescope") summary = writer_agent(research) return format_output(summary)

run()

Visualize the agent flow in the terminal:

peekai map

trace: multi_agent_pipeline ✓ ok 3.6s 236 tokens $0.000222

└── 🧠 researcher [agent] ✓ ok 2.3s └── 🤖 openai/gpt-4o [llm] ✓ ok 2.3s 102 tok $0.000115 └── 🧠 writer [agent] ✓ ok 1.3s └── 🤖 openai/gpt-4o [llm] ✓ ok 1.3s 134 tok $0.000107 └── 🔧 format_output [tool] ✓ ok 0ms

Trace Replay

Re-run any past trace — swap the model, inject a different tool response, see what would have changed:

Replay with the same model

peekai replay

Swap to a different model

peekai replay --model gpt-4o

Swap to Anthropic

peekai replay --model claude-3-5-sonnet-20241022

Inject a modified tool response

peekai replay --tool search="different search result"

The replay is saved as a new trace and shown side by side in the UI with token/cost deltas.

CLI Reference

Command Description

peekai list Show last 10 traces

peekai view Full span waterfall with I/O

peekai stats Total runs, tokens, cost by model

peekai map ASCII agent flow tree

peekai replay Re-run a trace (supports --model, --tool)

peekai ui Launch Streamlit dashboard

peekai clear Wipe local storage

All commands accept short trace IDs — the first 8 characters are enough.

Web Dashboard

peekai ui

Opens at http://localhost:8501 with four pages:

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

Decorators

Decorator What it does

@peekai.trace("name") Wraps a function as a top-level trace

@peekai.agent("name") Wraps a sub-agent — its LLM calls become children in the tree

@peekai.tool("name") Wraps a tool call as a TOOL span

peekai.init() options

peekai.init( db_path="./my_traces.db", # default: ~/.peekai/peekai.db openai=True, # patch OpenAI SDK (default True) anthropic=True, # patch Anthropic SDK (default True) litellm=True, # patch LiteLLM (default True) )

Traces are stored locally at ~/.peekai/peekai.db by default. You can open it directly with any SQLite viewer, back it up, or wipe it with peekai clear.

Supported SDKs

SDK Status Notes

OpenAI ✅ Auto-patched sync + async, streaming

Anthropic ✅ Auto-patched sync + async, create(stream=True) + stream() context manager

LiteLLM ✅ Auto-patched sync + async

Development

Clone and install

git clone https://github.com/oussamaKH63/peekai cd peekai uv sync --extra all # includes openai, anthropic, litellm, ui

Run tests

uv run pytest tests/ -v

Run the demos

uv run python examples/demo_agent.py uv run python examples/demo_multi_agent.py

Launch the UI

uv run peekai ui

Contributing

Install dev dependencies

uv sync --extra dev

Run linter

uv run ruff check src/

Run type checker

uv run mypy src/

Run tests

uv run pytest tests/ -v

PRs and issues are welcome. See CONTRIBUTING.md for more detail.

License

MIT © Oussema Khorchani

About

See every LLM call, tool use, and token spent — locally, with one line of code. No cloud. No account. No config.

pypi.org/project/peekai

Resources

Readme

License

MIT license

Contributing

Contributing

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

1 star

Watchers

0 watching

Forks

1 fork

Report repository

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python 100.0%