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

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.1
File Size Uploaded Provenance Actions
forge_lens_fl-0.2.1.tar.gz 190.8 kB With provenance Details for forge_lens_fl-0.2.1.tar.gz

Built distribution (wheel)

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

Total release size: 417.7 kB

Release files / forge_lens_fl-0.2.1.tar.gz

Download URL forge_lens_fl-0.2.1.tar.gz
Size 190.8 kB
Tags Source
SHA-256 checksum
How to use checksums
7687626453b0bb533bf6cf8d846c05e26d8978f4f4b79819e178a094a12cd315
BLAKE2b-256 checksum
How to use checksums
040e07c93a7e296cca34cf0c2c3383ff4498337877fcbae638e5828f878db92a
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.1-py3-none-any.whl

Download URL forge_lens_fl-0.2.1-py3-none-any.whl
Size 226.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8b833dd4aa78f0a0c69e2596f5897b4a40e3ea1d0a092af4b14c9d2077351546
BLAKE2b-256 checksum
How to use checksums
af9da7b2c148bf25db6271c1e08f8d058f711c0519be4c24e8a590f61d5fd4d9
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.1

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