Metadata-Version: 2.4
Name: thrdi
Version: 0.2.5
Summary: Trace any agentic CLI to a unified local store, queryable from the CLI.
Author: Duncan McKinnon
License: MIT
Project-URL: Homepage, https://github.com/duncankmckinnon/thirdeye
Project-URL: Issues, https://github.com/duncankmckinnon/thirdeye/issues
Classifier: License :: OSI Approved :: MIT License
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: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: starlette>=0.36
Requires-Dist: uvicorn>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: python-multipart>=0.0.20
Requires-Dist: logfire[datasets]>=4.25
Requires-Dist: genai-prices>=0.1.4
Requires-Dist: msgpack>=1.0
Requires-Dist: zstandard>=0.22
Requires-Dist: pyaml>=23.0
Requires-Dist: tomli>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: ruff>=0.7; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Dynamic: license-file

<p align="center">
  <a href="https://third3y3.com">
    <img src="docs/img/logo_transparent.png" alt="thirdeye" width="160" />
  </a>
</p>

[![PyPI](https://img.shields.io/pypi/v/thrdi.svg)](https://pypi.org/project/thrdi/)
[![Homebrew](https://img.shields.io/badge/homebrew-duncankmckinnon%2Ftap-orange)](https://github.com/duncankmckinnon/homebrew-tap)
[![CI](https://github.com/duncankmckinnon/thirdeye/actions/workflows/test.yml/badge.svg)](https://github.com/duncankmckinnon/thirdeye/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/duncankmckinnon/thirdeye/branch/main/graph/badge.svg)](https://codecov.io/gh/duncankmckinnon/thirdeye)
[![Python](https://img.shields.io/pypi/pyversions/thrdi.svg)](https://pypi.org/project/thrdi/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Trace every agent session on your machine — Claude Code, Codex, Cursor, Copilot —
into one history you and your agents can manage, search, and evaluate.

Thirdeye persists each session as a durable, append-only local event history.
Prompts, responses, tool calls, subagents, usage, and session metadata remain
available after the original agent process exits, giving both people and agents
a consistent record to inspect. Connect thirdeye to Pydantic Logfire to make
full use of that tracing data: explore complete execution trees, investigate
individual turns, and analyze behavior across sessions.

Visit [third3y3.com](https://third3y3.com) for guides and the full command reference.

## Installation

Homebrew is the simplest option on macOS and Linux. On Windows, use `pipx`
or `uv`.

```bash
brew install duncankmckinnon/tap/thirdeye
```

Alternatively, install with `pipx`:

```bash
pipx install thrdi
```

Or use `uv` or `pip`:

```bash
uv tool install thrdi
pip install thrdi
```

## Setup

Run the guided setup after installation:

```bash
thirdeye setup
```

The setup flow:

1. Selects the agent integrations you want to trace.
2. Installs the required hooks or agent configuration.
3. Offers to install thirdeye's bundled skills in the matching agent directories.
4. Optionally connects Pydantic Logfire and saves the write token used for export.

You can rerun setup whenever you add an agent or change your Logfire configuration.

## Logfire

[Pydantic Logfire](https://logfire.pydantic.dev) is where thirdeye's captured
data becomes a full observability experience. Once connected during setup, each
session appears as an OpenTelemetry trace containing agent turns, model calls,
tool executions, subagents, and available token usage and attributed costs.
Use Logfire to navigate the complete execution flow, query across sessions,
compare agent behavior, and investigate where time and tokens were spent.

Export happens outside the agent hook, so network latency does not interrupt
the agent session.

See [third3y3.com](https://third3y3.com) for Logfire configuration and export details.

## Skills

Thirdeye includes focused skills that let coding agents work directly with the
history it captures:

- **`use-thirdeye`** — inspect sessions, search events, debug tool calls, and
  analyze captured usage.
- **`thirdeye-evals`** — create evaluation rubrics, run evaluators, and interpret
  per-turn findings.
- **`thirdeye-review`** — audit agent behavior for inefficiencies and recommend
  concrete invocation or skill improvements.
- **`thirdeye-filter`** — translate natural-language questions from the UI into
  structured session and turn filters.
- **`thirdeye-logfire`** — configure, verify, and troubleshoot thirdeye's
  Logfire integration.

The setup flow can install these for you. To add them later, run
`thirdeye skills add`; use `thirdeye skills list` to see what is available.

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local
development, validation, and pull-request guidance.
