Skip to main content

Forge Lens

Forge Lens logo

Local-first, open-source agentic observability. Understand every agent execution. Trace every tool. Measure every cost. Investigate every failure. Prove every improvement.

Forge Lens receives, persists and explains agent executions — via OTLP/HTTP, OpenInference attributes, or its own SDKs — on your machine, with no mandatory external dependency.

Status

Cycles 00–01 (foundation, verified): contracts v1, OTLP/HTTP JSON ingestion, sanitization, SQLite WAL store, Python + TypeScript SDKs, CLI. Cycles 03–06 backend: temporal execution graph (/v1/graph/*), token/cost intelligence (/v1/traces/{id}/cost), failure classification + recorded replay + incident bundles (/v1/traces/{id}/failure|replay|incident), deterministic evaluation (/v1/eval/*), versioned datasets + regression gates — reports in docs/cycles/. Cycle 02: Angular Studio (apps/studio) — Trace Explorer with sortable/filterable list, waterfall with span detail, an evidence pane (cost/failure/loops/graph-analysis payloads rendered as JSON, plus eval results and recorded replay in tables), ops summary view, host-capability table, dark/light themes, URL-state sync, lazy routes, typed API client. Cycle 07: loop/no-progress detection (/v1/traces/{id}/loops), bounded specialist runtime (/v1/analyze/*), threshold alerts (/v1/alerts/evaluate), ops summary (/v1/ops/summary), MCP security observer (/v1/traces/{id}/security). Cycle 08: auth modes (none|key|keys) with API keys + roles + per-project tenancy, audit trail (/v1/admin/audit), retention (forge-lens prune|archive, /v1/admin/prune), TLS passthrough on serve. Cycle 09: SSE replay (/v1/traces/{id}/stream), measured benchmarks at 1k/10k/100k spans (scripts/benchmark.py → docs/benchmarks/), archive-before-delete lifecycle. Cycle 10: honest host-capability matrix (/v1/capabilities), Claude Code JSONL importer (import-claude), MCP stdio observer (mcp-serve), install lifecycle receipts (install-status), 7 skills in skills/. Cycle 11: CycloneDX SBOM generator (scripts/gen_sbom.py), release workflow with OIDC trusted publishing + version gate, CHANGELOG.md, docs/versioning.md, Studio CI job. Cycle 12: efficiency intelligence (/v1/intel/efficiency, /v1/traces/{id}/efficiency), cohort regression (/v1/intel/regress), candidate recommendations (/v1/traces/{id}/recommendations), graph centrality/concentration analysis (/v1/graph/traces/{id}/analysis).

Quickstart

Portable install (same model as the other Forge projects — venv under ~/.forge/installs/forge-lens, launcher on PATH, no project-venv touch):

./install.sh              # POSIX; . .\install.ps1 on PowerShell
forge-lens init .
forge-lens serve          # API on http://127.0.0.1:7777
forge-lens doctor

Dev checkout alternative: uv sync --extra server && uv run forge-lens ....

Instrument an agent:

from forge_lens.sdk import LensTracer
from forge_lens.sdk.exporter import HTTPExporter

tracer = LensTracer(
    service_name="my-agent",
    exporter=HTTPExporter("http://127.0.0.1:7777"),
)

with tracer.agent("researcher"):
    with tracer.llm_call("claude-sonnet-4", provider="anthropic") as s:
        tracer.record_usage(s, input_tokens=200, output_tokens=80, total_tokens=280)
    with tracer.tool_call("web_search"):
        ...  # call the tool

Inspect:

forge-lens traces list
forge-lens traces show <trace-id>

A runnable offline demo (SDK → pipeline → store → read-back, no server): uv run python examples/quickstart.py

Principles

  • Local-first — SQLite WAL by default; works fully offline.
  • Evidence-first — every claim carries provenance (observed / imported / derived / inferred / unknown). Inferred never silently becomes observed.
  • Safe by default — capture=metadata redacts secrets and drops prompt bodies unless you opt into full.
  • OTel/OpenInference compatible — OTLP/HTTP JSON ingest, openinference.* attribute mapping, W3C traceparent propagation.

Documentation

See docs/ — architecture, guides, API/CLI/contracts reference, ADRs and cycle reports (PT-BR first, EN planned).

  • docs/guides/quickstart.md — first trace in minutes
  • docs/guides/operations-runbook.md — serve, auth modes, retention, backups, monitoring, alert rules
  • docs/guides/troubleshooting.md — symptom → cause → fix
  • docs/guides/failure-investigation.md — failure taxonomy (§05.3), root-cause hypotheses (§05.4), eval suggestions (§12.7)

Metadata

Release files for forge-lens-fl 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for forge-lens-fl 0.2.0
File Size Uploaded Provenance Actions
forge_lens_fl-0.2.0.tar.gz 189.9 kB With provenance Details for forge_lens_fl-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for forge-lens-fl 0.2.0
File Interpreter ABI Platform Actions
forge_lens_fl-0.2.0-py3-none-any.whl Python 3 none any Details for forge_lens_fl-0.2.0-py3-none-any.whl

Total release size: 415.8 kB

Release files / forge_lens_fl-0.2.0.tar.gz

Download URL forge_lens_fl-0.2.0.tar.gz
Size 189.9 kB
Tags Source
SHA-256 checksum
How to use checksums
98db8025a530f6197c22b4c9190ed63e5f94af75406d4ce01523811cc7ccc1e3
BLAKE2b-256 checksum
How to use checksums
cc1fe1cd168346f7f5923f187ad8f9a42066ecb9bad9ad801556413cbeccfbab
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / forge_lens_fl-0.2.0-py3-none-any.whl

Download URL forge_lens_fl-0.2.0-py3-none-any.whl
Size 225.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
36dbb840bcec45100cdeedf2b8cf5e3860303e670fecf5b9ac0ac96c0cd9c346
BLAKE2b-256 checksum
How to use checksums
757a661d4202afccc176995c4dcc713cbe187867b1df9420f36c823b711fe246
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for forge-lens-fl 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for forge_lens_fl-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page