Forge Lens
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=metadataredacts secrets and drops prompt bodies unless you opt intofull. - 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 minutesdocs/guides/operations-runbook.md— serve, auth modes, retention, backups, monitoring, alert rulesdocs/guides/troubleshooting.md— symptom → cause → fixdocs/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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.