LTF — Loop Trace Format

The open standard for AI agent loop telemetry — record every iteration, debug any failure, benchmark any design.

LTF is a JSONL-based trace format for recording AI agent loop iterations — the act → verify → decide cycle that is the fundamental unit of work in loop engineering. Every other tool in the loop-eng ecosystem reads and writes this format.

Why LTF?

Every observability tool traces individual LLM calls or tool invocations. Nothing traces loop iterations — the multi-step act → verify → decide cycle that defines loop engineering.

Existing Format	What It Covers	Gap LTF Fills
OpenTelemetry GenAI	Individual LLM calls (spans)	No loop concepts (iterations, convergence, verification phases)
Langfuse / LangSmith	LLM call chains with cost	Proprietary format, no iteration semantics
Claude Code / Codex logs	Session-level streaming	Internal format, not cross-platform

LTF fills this gap the way OpenTelemetry filled it for distributed systems — but for the loop layer.

Quick Start

Parse traces (TypeScript)

npm install @loop-eng/ltf

import { parseTrace, computeMetrics } from '@loop-eng/ltf';

const events = parseTrace(traceContent);
const metrics = computeMetrics(events);
console.log(`Iterations: ${metrics.totalIterations}, Cost: $${metrics.totalCostUsd}`);

Parse traces (Python)

pip install loopeng-ltf

from ltf import parse_trace, compute_metrics

events = parse_trace("trace.ltf.jsonl")
metrics = compute_metrics(events)
print(f"Iterations: {metrics.total_iterations}, Cost: ${metrics.total_cost_usd}")

Validate traces (CLI)

go install github.com/loop-eng/ltf/cli/cmd/ltf@latest
ltf validate trace.ltf.jsonl
ltf stats trace.ltf.jsonl

Auto-trace Claude Code sessions

bash <(curl -s https://raw.githubusercontent.com/loop-eng/ltf/main/adapters/claude-code/install.sh)

Trace Format

Each line is a self-contained JSON event. Only 4 fields are required:

{"ltf_version":"1.0","loop_id":"abc-123","timestamp":"2026-07-01T10:00:00Z","phase":"act","iteration":1,"agent":{"name":"claude-sonnet-4-6","role":"implementer"},"action":{"type":"file_edit","target":"src/auth.ts"},"tokens":{"input":8000,"output":400},"cost_usd":0.030}
{"ltf_version":"1.0","loop_id":"abc-123","timestamp":"2026-07-01T10:00:12Z","phase":"verify","iteration":1,"action":{"type":"test_run","target":"npm test"},"verification":{"command":"npm test","exit_code":0},"result":{"status":"success"}}
{"ltf_version":"1.0","loop_id":"abc-123","timestamp":"2026-07-01T10:00:12Z","phase":"terminate","result":{"status":"success","detail":"goal_met"}}

Phase Taxonomy

Phase	Meaning	Example
plan	Agent creates/updates a plan	"Break task into 3 subtasks"
act	Agent takes an action	"Edit file", "Run command"
verify	Separate verifier checks results	"Tests: 5 pass, 2 fail"
decide	Loop controller decides next step	"Continue", "Retry", "Stop"
error	Something went wrong	"Tool timeout", "API 429"
terminate	Loop ended	"Goal met", "Budget exhausted"

Repository Structure

ltf/
├── spec/v1.0/           # Specification, JSON Schema, example traces
├── parsers/
│   ├── typescript/       # @loop-eng/ltf (npm)
│   └── python/           # loopeng-ltf (PyPI)
├── adapters/
│   └── claude-code/      # PostToolUse hook for automatic tracing
└── cli/                  # Go CLI: ltf validate, ltf stats

Relationship to OpenTelemetry

LTF is complementary to OpenTelemetry, not competing. LTF traces a layer above OTEL spans — a single LTF iteration event may encompass multiple OTEL spans. The TypeScript package includes an OTEL exporter that maps LTF events to OTEL spans:

import { exportToOTEL } from '@loop-eng/ltf/otel';

Ecosystem

LTF is the flywheel of the loop-eng toolkit:

Tool	Role
LoopGuard	Emits LTF events on intervention
LoopCtl	Reads LTF for live dashboards
Kit	Generates LTF configurations
Loop-Bench	Computes metrics from LTF traces
LoopReplay	Replays LTF traces step-by-step

License

MIT