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

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.3
File Size Uploaded Provenance Actions
forge_lens_fl-0.2.3.tar.gz 213.0 kB With provenance Details for forge_lens_fl-0.2.3.tar.gz

Built distribution (wheel)

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

Total release size: 467.5 kB

Release files / forge_lens_fl-0.2.3.tar.gz

Download URL forge_lens_fl-0.2.3.tar.gz
Size 213.0 kB
Tags Source
SHA-256 checksum
How to use checksums
c1bc89cf1429de0e382f32dd6f1f29303915e12a9cec3e71941836479121cf6e
BLAKE2b-256 checksum
How to use checksums
83a01e9e22bf73d388dff0220f00421dcc53e91648c8e060f0994e72b4e078e7
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 12, 2026.

Transparency log

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

Download URL forge_lens_fl-0.2.3-py3-none-any.whl
Size 254.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b2e9ea8105ed5a36b66e5d397d2de42a7d28a206121ab51776812da23d99eaaa
BLAKE2b-256 checksum
How to use checksums
663fa6d019994c7eac9d78143fb6159227827bade26e37968dd3c3e7ba2ab1c5
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 12, 2026.

Transparency log

Security for forge-lens-fl 0.2.3

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.3.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 12, 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