reflect

Evidence, Not Vibes.
Evidence-backed improvement for AI agent work across teams.

Website · Live dashboard · PyPI · Contributing · Changelog

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, then install and configure Reflect with one command:

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?

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:

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

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:

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:

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:

reflect setup --text-capture-mode metadata

Project-local agent wiring is opt-in:

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.

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

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:

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 for module ownership, data flow, and architectural guardrails.

Common Commands

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:

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:

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:

reflect completion --install
reflect setup --shell-completion
reflect completion --shell zsh

Development

Source development uses Poetry:

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:

poetry run python scripts/build_dashboard.py

Before a release:

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 for architecture, development, and review conventions, and the analysis schema for canonical telemetry fields.

License

Apache-2.0