Metadata-Version: 2.4
Name: o11y-reflect
Version: 0.9.7
Summary: Local-first telemetry and measurable workflow improvement for AI coding agents
License-Expression: Apache-2.0
Project-URL: Homepage, https://o11y.dev
Project-URL: Repository, https://github.com/o11y-dev/reflect
Project-URL: Documentation, https://github.com/o11y-dev/reflect#readme
Project-URL: Issues, https://github.com/o11y-dev/reflect/issues
Project-URL: Changelog, https://github.com/o11y-dev/reflect/blob/main/CHANGELOG.md
Keywords: observability,opentelemetry,ai-agents,telemetry,workflow-improvement,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: orjson>=3.0
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn>=0.20
Requires-Dist: grpcio>=1.60
Requires-Dist: opentelemetry-proto>=1.20
Requires-Dist: pydantic>=2.0
Requires-Dist: mcp<2,>=1.28
Requires-Dist: opentelemetry-hooks<0.15,>=0.14
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: httpx>=0.24; extra == "test"
Provides-Extra: e2e
Requires-Dist: playwright>=1.40; extra == "e2e"
Provides-Extra: omega
Requires-Dist: omega-memory<2,>=1.5; extra == "omega"
Dynamic: license-file

<p align="center">
  <a href="https://reflect.o11y.dev/">
    <img src="docs/favicon.svg" width="72" height="72" alt="Reflect logo">
  </a>
</p>

<h1 align="center">reflect</h1>

<p align="center">
  <strong>Evidence, Not Vibes.</strong><br>
  Evidence-backed improvement for AI agent work across teams.
</p>

<p align="center">
  <a href="https://pypi.org/project/o11y-reflect/"><img src="https://img.shields.io/pypi/v/o11y-reflect" alt="PyPI version"></a>
  <a href="https://pypi.org/project/o11y-reflect/"><img src="https://img.shields.io/pypi/pyversions/o11y-reflect" alt="Supported Python versions"></a>
  <a href="https://github.com/o11y-dev/reflect/actions/workflows/test.yml"><img src="https://github.com/o11y-dev/reflect/actions/workflows/test.yml/badge.svg" alt="CI status"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/o11y-dev/reflect" alt="Apache 2.0 license"></a>
</p>

<p align="center">
  <a href="https://reflect.o11y.dev/">Website</a> ·
  <a href="https://reflect.o11y.dev/report.html?report=reports/showcase.json">Live dashboard</a> ·
  <a href="https://pypi.org/project/o11y-reflect/">PyPI</a> ·
  <a href="CONTRIBUTING.md">Contributing</a> ·
  <a href="CHANGELOG.md">Changelog</a>
</p>

Reflect is a local-first improvement loop for AI coding agents. It captures
what happened, discovers repeated engineering procedures, lets a developer
review a bounded workflow, and measures whether comparable future tasks
improved.

No hosted backend and no Reflect account are required. Telemetry, task
evidence, workflow reviews, and SQLite state remain on your machine.

## Quick Start

Reflect requires Python 3.12+. The supported operating systems are macOS and
Linux. Review the public [install script](https://reflect.o11y.dev/install.sh),
then install and configure Reflect with one command:

```bash
curl -fsSL https://reflect.o11y.dev/install.sh | sh
reflect doctor
reflect
```

For a fresh installation, the script uses an available package manager in this
order: pipx, uv, then Python's pip in an isolated environment. It never uses
`sudo` or changes the system Python. It runs `reflect setup` after installation;
in a terminal you choose the integrations and text-capture mode, while
non-interactive use defaults to all detected agents with metadata-only capture.

Re-run the same command to update Reflect. The script detects whether the active
installation belongs to pipx, uv, or pip, upgrades it with that owner, and
preserves the existing setup.

Prefer manual installation?

```bash
pipx install o11y-reflect
# or: uv tool install o11y-reflect
reflect setup
```

`reflect setup` starts the local OTLP gateway, registers `reflect-mcp`, and
installs the packaged Reflect skills. On macOS it can register the gateway and
report server for login startup; pass `--no-autostart` to opt out.

`reflect doctor` is the source of truth for capture readiness. It distinguishes
configuration from an observed event, an ingested session, and reconciled
logical calls.

### Ask through your agent

Use Reflect in the agent where the work is already happening:

```text
Use Reflect to explain why this session was expensive and what should improve.

Use Reflect to find a repeated engineering procedure worth making reusable.

Use Reflect to prepare an internal AI budget increase request from measured work.

Use Reflect to show whether an installed workflow improved comparable tasks.
```

The packaged skill starts a non-trivial repository task with
`reflect_context`, keeps selected guidance tied to a task run, and closes it
with `reflect_complete` after validation. It can inspect evidence and prepare a
review, but it cannot install or change a workflow without explicit human
approval.

### Explore visually in the UI

```bash
reflect
```

The browser opens at `http://127.0.0.1:8765`. It reads the same local SQLite
evidence as the CLI and MCP server. The normal refresh-enabled server prepares
new telemetry immediately and every five minutes; `reflect server start` is
snapshot-only unless `--refresh` is supplied.

No data yet? Open the bundled cross-agent demonstration:

```bash
reflect --demo
```

The demo contains Claude, Codex, Copilot, Cursor, and historical Gemini
sessions. Demo coverage is not a claim that every provider surface is currently
live-supported.

## From Personal Reflection to Organizational Improvement

The product loop is:

> task contract -> execution evidence -> human review -> installed workflow ->
> comparable future tasks -> measured impact

The browser has six surfaces:

| Surface | What it answers |
|---|---|
| **Sessions** | What happened, what did it cost, and which source evidence is available? |
| **Inbox** | Which findings and repeated behaviors need investigation before becoming interventions? |
| **Workflows** | Which bounded intervention contracts need review, installation, or rollback? |
| **Skills** | Which versioned procedures exist, where are they installed, and have agents used them? |
| **Impact** | Did comparable task outcomes move after installation, and is attribution supported? |
| **Explore** | What do usage, tools, MCP, graph, context, and task contracts show? |

A finding or loop is evidence, not an installed improvement. Approval and
installation are separate. Impact begins only after a workflow is installed,
and missing baseline evidence is shown as unavailable rather than zero.

### Skills Registry

Skills are durable, versioned procedures—not another label for findings or
workflow drafts. The Skills surface shows registry state, installation targets,
source evidence, observed exposure, and measured outcomes without implying that
a registered skill is installed or effective. Use `reflect skills` or
`reflect_skills` for the same local registry through the CLI or MCP.

## What Reflect Can Prove

Reflect derives these views from canonical local evidence:

- session conversations, outcomes, duration, agents, and source provenance
- exact or explicitly estimated tokens and cost, with model and cache breakdowns
- one logical count per tool or MCP invocation
- failures, retries, recovery, verification, edits, and delegation
- bounded task executions and comparable task archetypes
- workflow contract adherence before and after installation
- measured outcome shifts and the evidence quality required for attribution

Reflect does not rank developers or agents. It does not combine unrelated task
types, treat an entire long-lived session as one task, or convert correlation
into causality.

## Trust and Privacy Contract

- Local traces, logs, native session data, and `reflect.db` stay under local
  state paths and supported agent-owned stores.
- Prompt and response text capture is opt-in. Setup offers metadata-only,
  masked-text, and full-text modes.
- Normalized evidence keeps source provenance and marks token/cost estimates.
- External or repository writes require exact preview and explicit approval;
  apply and rollback are separate recorded actions.
- Workflow impact exposes compared task IDs, cohort size, missing telemetry,
  evidence cutoff, and the reason a claim is withheld.
- Retention can remove telemetry without silently installing, applying, or
  changing reviewed workflows.

For non-interactive setup, choose capture explicitly:

```bash
reflect setup --text-capture-mode metadata
```

Project-local agent wiring is opt-in:

```bash
reflect setup --agent "Claude Code" --local-agent "Claude Code"
```

## Agent Capability Truth

Support is declared per surface. A working MCP connection does not prove native
tokens, cost, hooks, or transcripts.

| Agent | Status | Current evidence path |
|---|---|---|
| Claude Code | Supported | Native OTel + hooks + native sessions |
| Cursor | Supported | Session/log adapters + optional hooks |
| Antigravity | Partial | Reflect MCP task runs; native tool telemetry unverified |
| GitHub Copilot | Supported | Native OTel + hooks + native sessions |
| OpenAI Codex CLI | Supported | Native OTel + native sessions |
| OpenCode | Supported | Native SQLite sessions + hooks |
| Windsurf | Supported | Hooks + configuration snapshots |
| Gemini CLI | Historical | Historical native OTel + session adapter |

Planned agents may be inventoried for configuration or skill paths, but Reflect
does not label them as capturing.

Antigravity's current CLI alias is `agy`; Windsurf MCP setup is editor-config only.

The registry in `src/reflect/agent_capabilities.py` feeds setup, doctor, aliases,
skill distribution, MCP configuration, and local-agent tests.

## How Capture Works

```mermaid
flowchart LR
    A[Native OTel and hooks] --> B[Bounded raw JSONL segments]
    C[Agent-native stores] --> D[Checkpointed ingestion]
    B --> D
    D --> E[Canonical normalization]
    E --> F[(Local SQLite)]
    F --> G[Sessions and Explore]
    F --> H[Findings and workflows]
    H --> I[Installed version]
    I --> J[Comparable-task impact]
```

The gateway appends to `otel-traces.active.jsonl` and
`otel-logs.active.jsonl`, rotating immutable closed segments at a bounded size.
Refresh checkpoints each source, normalizes new records, and deletes only
closed segments whose events normalized successfully. Use
`--keep-processed-raw` when replay files must be retained.

The combined trace-and-log replay buffer has a 4 GiB hard admission limit by
default. At the limit the gateway preserves every existing byte and rejects new
HTTP telemetry with `507` or gRPC telemetry with `RESOURCE_EXHAUSTED`; it never
deletes unprocessed evidence to make room. The dashboard, `reflect doctor`, and
`reflect gateway status` warn at 80% and show when capture is paused. A
successful refresh removes eligible processed closed segments and capture then
resumes automatically.

Operators can override the positive byte and cadence values before starting the
managed services:

```bash
REFLECT_OTLP_MAX_BYTES=4294967296           # combined raw traces + logs
REFLECT_OTLP_SEGMENT_BYTES=268435456        # one active segment
REFLECT_REFRESH_INTERVAL_SECONDS=300        # refresh-enabled report server
```

`tool_calls` stores one logical invocation. `mcp_calls` is a one-to-one metadata
extension for MCP server, tool, transport, and protocol identity, not a second
call ledger.

See the [contribution guide](CONTRIBUTING.md#architecture-and-ownership) for
module ownership, data flow, and architectural guardrails.

## Common Commands

```bash
reflect usage                         # current runtime usage
reflect usage --global --period week # all matching local usage for seven days
reflect refresh --json               # explicit ingest and snapshot refresh
reflect improve                      # scoped findings
reflect loops                        # observed stalled or productive loops
reflect workflows list               # reviewable and historical workflow state
reflect skills                       # durable skill registry
reflect memory sync .                # sync scoped instruction memory
reflect doctor                       # capture and installation diagnostics
```

Read commands inspect an existing query-only snapshot. Commands that refresh,
install, roll back, prune, or vacuum are explicit mutations.

### Direct OTLP input

An explicit trace file remains supported for imports and tests:

```bash
reflect --otlp-traces path/to/otel-traces.json
```

If a sibling `otel-logs.json` exists, Reflect reads it as the corresponding log
source. The managed gateway uses the bounded `.active.jsonl` segment names.

## Workflow and Impact Lifecycle

Reflect keeps these states separate:

1. Evidence produces a finding or loop.
2. A workflow candidate defines a typed procedure and validation window.
3. The developer's human review approves an exact immutable revision.
4. Explicit apply installs that version at one target.
5. The next comparable task executions record exposure and adherence.
6. Impact compares the frozen baseline with the bounded post-install cohort.
7. The developer keeps, revises, or rolls back the installation.

An approved-but-uninstalled workflow is never selected as executable guidance.
Workflow identity comes from contract semantics; a title or wording edit alone
does not invent a new procedure.

## Reflect MCP

`reflect-mcp` is a local stdio MCP server. Its main tools are:

- `reflect_context` — start task-specific guidance
- `reflect_record_milestone` — record idempotent workflow checkpoints
- `reflect_complete` — close the task after validation
- `reflect_improvements`, `reflect_patterns`, `reflect_skills`, and
  `reflect_impact` — bounded read-only evidence
- `reflect_explain` and `reflect_usage` — provenance and exact usage
- `reflect_review_change` — return an exact diff, target, risks, and rollback
- `reflect_apply_change` — consume only the explicitly approved exact review

Setup writes the appropriate client configuration for Claude, Cursor,
Antigravity, Copilot, Codex, OpenCode, and Windsurf. Windsurf has no supported
headless test surface. Historical Gemini telemetry parsing is independent of
current Antigravity MCP configuration.

To verify one task lifecycle after capture:

```bash
reflect usage --session <session-id> --refresh --json
```

A task that called `reflect_context` and `reflect_complete` should show two
successful logical MCP calls once its runtime telemetry has been ingested.

## Shell Completion

Setup leaves shell files unchanged by default. Review the exact target paths and
managed block before an explicit Bash, Zsh, or Fish installation:

```bash
reflect completion --install
reflect setup --shell-completion
reflect completion --shell zsh
```

## Development

Source development uses Poetry:

```bash
poetry install --extras test
poetry run reflect --demo
poetry run reflect doctor
poetry run pytest tests/test_dashboard_sql_api.py -q
poetry run pytest -q
```

The browser is authored in `src/reflect/frontend/`. Regenerate both shipped
single-file artifacts after client changes:

```bash
poetry run python scripts/build_dashboard.py
```

Before a release:

```bash
poetry run ruff check .
poetry run pytest -q --no-cov
poetry run python scripts/release_workflow.py release-notes 0.9.7
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture, development, and review
conventions, and [the analysis schema](docs/ai-observability-schema.md) for
canonical telemetry fields.

## License

[Apache-2.0](LICENSE)
