Agent Observatory

See what your agents are doing, live. Agent Observatory watches local Codex and Claude Code sessions, receives OpenTelemetry from instrumented agents, and brings tasks, tool calls, MCP, traces, tokens, errors, and host activity into one terminal cockpit and local web dashboard.

Short demo using synthetic example data. No real session logs or user prompts are included.

Start in one command

Requires Python 3.11+. Install uv if needed, then:

uv tool install agent-observatory-cli
agent-observatory

Or install it into the active Python environment with python -m pip install agent-observatory-cli.

The terminal cockpit discovers recent local Codex and Claude Code sessions automatically. Press b to open the local web dashboard. It listens on 127.0.0.1:14318.

Already cloned the repository? Run the installer for your shell:

./scripts/install.sh

.\scripts\install.ps1

These install the checkout as an isolated uv tool. Re-run the script after pulling an update. No administrator access is needed.

What you get

• Agents: distinct sessions, project, current task, model, recent actions, and activity state.
• Activity: readable user/assistant messages, shell commands, file changes, browser events, model use, and tool results.
• MCP: server and tool calls with readable arguments and results, an Errors filter, latency, and direct links to the execution span.
• Traces: parent/child spans, model usage, errors, and evidence for each operation.
• Host: known local agent processes and basic resource use, shown separately from sessions.
• Web dashboard: searchable live activity with the same local receiver.

The cockpit adapts from compact terminals to wide workspaces. Search stays with each view, Enter inspects a row, e expands the details, and Esc returns to the list. Drag to highlight inspector text and press Ctrl+C to copy it; c copies the current details. Activity, MCP Calls, and Traces include Older / Newer / Latest controls for stored history, and Alt+Left returns from a linked trace to the event you were reading.

The receiver stores data in a local SQLite file. Native session capture is bounded and redacts recognizable credentials on a best-effort basis. Choose metadata-only capture with --metadata-only. See Privacy and capture boundaries.

Connect other agents

Send OpenTelemetry traces, logs, and metrics over OTLP/HTTP, or use the Python and JavaScript clients:

• Python setup and automatic SDK capture
• Node.js client
• OTLP, receiver, and deployment configuration
• Complete usage guide and examples

Develop

git clone https://github.com/abhishekash/agent-observatory.git
cd agent-observatory
uv tool install --editable .
python -m unittest discover -s tests -v

Contributions and bug reports are welcome. See CONTRIBUTING.md and open an issue.

Maintainers can follow the PyPI publishing guide to release a version with Trusted Publishing.

License

Agent Observatory is distributed under the MIT License.