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

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.4
File Size Uploaded Provenance Actions
forge_lens_fl-0.2.4.tar.gz 213.5 kB With provenance Details for forge_lens_fl-0.2.4.tar.gz

Built distribution (wheel)

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

Total release size: 468.5 kB

Release files / forge_lens_fl-0.2.4.tar.gz

Download URL forge_lens_fl-0.2.4.tar.gz
Size 213.5 kB
Tags Source
SHA-256 checksum
How to use checksums
a099b50797a888d69688e08c9f6ec3e943efe2c0f941ff22d2a7c039fc21b26a
BLAKE2b-256 checksum
How to use checksums
eec687ba5eb3fc23f6122e40ee391797b44c086f6f287cbab65b31813827774d
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 13, 2026.

Transparency log

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

Download URL forge_lens_fl-0.2.4-py3-none-any.whl
Size 255.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3315cc0d18d028698dafe4502fc4078bc530f1d961c5e20241f537830ec170d6
BLAKE2b-256 checksum
How to use checksums
d53aa865ec855391a0642cfa13d1bfb0e2e935d7337dc87448fd60dd7c034c47
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 13, 2026.

Transparency log

Security for forge-lens-fl 0.2.4

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.4.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 13, 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