Metadata-Version: 2.4
Name: agent-observatory-cli
Version: 0.1.0
Summary: Local agent trace receiver and investigation dashboard
License-Expression: MIT
Project-URL: Repository, https://github.com/abhishekash/agent-observatory
Project-URL: Issues, https://github.com/abhishekash/agent-observatory/issues
Keywords: agents,observability,opentelemetry,otlp,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual<9,>=8.2
Provides-Extra: auto
Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == "auto"
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.27; extra == "auto"
Requires-Dist: openinference-instrumentation-openai>=0.1; extra == "auto"
Requires-Dist: openinference-instrumentation-anthropic>=0.1; extra == "auto"
Requires-Dist: openinference-instrumentation-langchain>=0.1; extra == "auto"
Provides-Extra: langchain
Requires-Dist: langchain-core<2,>=0.3.9; extra == "langchain"
Provides-Extra: openai-agents
Requires-Dist: openai-agents<2,>=0.1.0; extra == "openai-agents"
Dynamic: license-file

# Agent Observatory

[![CI](https://github.com/abhishekash/agent-observatory/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/abhishekash/agent-observatory/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/agent-observatory-cli)](https://pypi.org/project/agent-observatory-cli/)
![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)
![OpenTelemetry OTLP](https://img.shields.io/badge/OpenTelemetry-OTLP-425CC7?logo=opentelemetry&logoColor=white)
![Local first](https://img.shields.io/badge/data-local--first-2E8B57)

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

<p align="center">
  <img src="media/terminal-demo.gif" alt="Animated preview of the Agent Observatory terminal cockpit with agents, MCP calls, traces, and host processes" width="960">
</p>

<p align="center"><em>Short demo using synthetic example data. No real session logs or user prompts are included.</em></p>

## Start in one command

Requires Python 3.11+. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if needed, then:

```bash
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:

```bash
./scripts/install.sh
```

```powershell
.\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](docs/privacy.md).

## 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](docs/python.md)
- [Node.js client](docs/javascript.md)
- [OTLP, receiver, and deployment configuration](docs/receiver.md)
- [Complete usage guide and examples](docs/usage.md)

## Develop

```bash
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](CONTRIBUTING.md) and [open an issue](https://github.com/abhishekash/agent-observatory/issues).

Maintainers can follow the [PyPI publishing guide](docs/publishing.md) to release a version with Trusted Publishing.

## License

Agent Observatory is distributed under the [MIT License](LICENSE).
