mimir-observe 0.5.0

Auto-instrumentation and visibility for AI agents — OpenAI Agents SDK, Claude SDK, and more.

mimir-observe

Auto-instrumentation and visibility for AI agents. Two lines of code, zero config.

pip install mimir-observe

After installing, run python -m mimir.cli quickstart for the full getting-started guide with copy-paste snippets and the Claude Code onboarding prompt.

Quick start

1. Add instrumentation (2 lines)

Pick the one that matches your stack:

import mimir

# Raw OpenAI client (chat.completions.create)
mimir.instrument_openai()

# Raw Anthropic client (messages.create)
mimir.instrument_anthropic()

# OpenAI Agents SDK (Runner.run / Runner.run_streamed)
mimir.instrument_openai_agents()

# Claude Agent SDK (query)
mimir.instrument_claude()

Add these lines at the top of your entry point, before any API calls. That's it. Your existing code stays exactly the same.

2. Start the dashboard

In a separate terminal:

python -m mimir.cli dashboard

Open http://localhost:9847 to see your runs.

3. There is no step 3

Every API call and agent run is now captured automatically. The dashboard shows:

• Agent list with run counts, models, and tools
• Run timeline with every tool call (args + results), reasoning block, and token usage
• Run diffing -- side-by-side comparison of any two runs
• Divergence detection -- flags agents whose reruns follow different tool patterns

What gets captured

Data	How
Tool calls	Name, arguments, result, duration
Reasoning	Model output text between tool calls
Token usage	Input/output tokens per call
Cost	If set via run.set_cost()
Run duration	Wall clock time
Run status	Success or error
Input/output	Prompt and final result

Which instrument function do I use?

Your code uses	Function
from openai import OpenAI	mimir.instrument_openai()
from anthropic import Anthropic	mimir.instrument_anthropic()
from agents import Runner	mimir.instrument_openai_agents()
from claude_code_sdk import query	mimir.instrument_claude()

You can call multiple if your project uses more than one SDK.

Multi-turn agentic loops

If your agent calls the API multiple times in a loop, wrap it with mimir.trace() so all calls are grouped as one named run:

import mimir
mimir.instrument_openai()  # or instrument_anthropic()

from openai import OpenAI
client = OpenAI()

with mimir.trace("Migration Planner"):
    # Every API call inside here becomes a step in one run
    response = client.chat.completions.create(model="gpt-4o", messages=[...])
    response = client.chat.completions.create(model="gpt-4o", messages=[...])
    response = client.chat.completions.create(model="gpt-4o", messages=[...])

This is important when you have multiple agents using the same model — without trace(), they all get lumped together. Each trace("name") creates a distinct agent on the dashboard.

Without the wrapper, each API call creates its own run — fine for single calls, wrong for loops.

How it works

Mimir monkey-patches the SDK at the class level when you call instrument_*(). Every subsequent API call is intercepted, telemetry is extracted from the request/response, and it's sent to the local dashboard via fire-and-forget HTTP. Your agent code is never blocked or slowed down.

• Zero external dependencies (stdlib only)
• All data stays local (~/.mimir/)
• Dashboard down? Agent runs normally, no errors
• Uninstrument anytime: mimir.uninstrument_openai(), etc.

Manual instrumentation

For custom setups where auto-instrumentation doesn't fit:

import mimir

t = mimir.task(
    name="My Agent",
    config="what it does",
    tools=["search", "write"],
    model="gpt-4o",
)

with t.run(input={"prompt": "user input"}) as run:
    run.tool("search", {"q": "test"}, "3 results", duration_ms=150)
    run.reasoning("Found relevant results, writing report...")
    run.tool("write", {"file": "report.md"}, "ok", duration_ms=50)
    run.set_usage(1500, 800)
    run.set_output("Report written")

Onboarding with Claude Code

If you use Claude Code, paste this prompt to have it instrument your project automatically:

Install and set up Mimir agent observability in this project.

Step 1: pip install mimir-observe (if not already installed). Import as `import mimir`.

Step 2: Find the entry point(s) and determine which SDK is used:
  - `from openai import OpenAI` → add `mimir.instrument_openai()`
  - `from anthropic import Anthropic` → add `mimir.instrument_anthropic()`
  - `from agents import Runner` → add `mimir.instrument_openai_agents()`
  - `from claude_code_sdk import query` → add `mimir.instrument_claude()`

Add the 2 lines (import + instrument call) at the top of each entry point,
BEFORE any API calls. No other code changes needed.

Step 3: If the code has multi-turn agentic loops (calling the API multiple times
in a while/for loop), wrap each agent's loop with mimir.trace("Agent Name") so
all turns become steps in one run instead of separate runs:

    with mimir.trace("Migration Planner"):
        # ... the existing loop goes here, unchanged ...

Each distinct agent should get its own mimir.trace() wrapper with a unique name.
Single API calls outside a loop do NOT need this wrapper — they auto-create runs.

Step 4: Start the dashboard: python -m mimir.cli dashboard

CLI

python -m mimir.cli dashboard              # start on :9847
python -m mimir.cli dashboard --port 8080  # custom port
python -m mimir.cli version                # print version

Requirements

• Python 3.10+
• No external dependencies

The SDKs you want to instrument (openai, anthropic, openai-agents, etc.) must be installed separately.