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)

# Remote install
go install github.com/loop-eng/ltf/cli/cmd/ltf@latest

# Or local install from source
cd cli && make install

ltf validate trace.ltf.jsonl
ltf stats trace.ltf.jsonl

Auto-trace Claude Code sessions

# Clone the repo and run the installer from within it
git clone https://github.com/loop-eng/ltf.git
cd your-project  # navigate to the project you want to trace
bash /path/to/ltf/adapters/claude-code/install.sh

The install script copies the hook into your project's .loop/ directory and configures .claude/settings.json with PostToolUse and Stop hooks. Requires jq.

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) + OTEL exporter
│   └── python/           # loopeng-ltf (PyPI)
├── adapters/
│   └── claude-code/      # PostToolUse + Stop hooks for automatic tracing
├── cli/                  # Go CLI: ltf validate, ltf stats, ltf version
├── demo/                 # Demo scripts and E2E cross-language tests
└── FINDINGS.md           # Bug hunt audit trail (3 rounds, 70 findings)

Local Development

TypeScript parser

cd parsers/typescript
npm install
npm run build        # tsup → dual CJS/ESM in dist/
npm test             # vitest (77 tests)
npm run lint         # eslint
npm run typecheck    # tsc --noEmit

Python parser

cd parsers/python
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest               # 71 tests
ruff check ltf/

Go CLI

cd cli
make build           # → bin/ltf
make test            # go test -race
make install         # copies to $GOPATH/bin
make lint            # golangci-lint
make fuzz            # 30s fuzz run

Adapter

cd adapters/claude-code
bash test-hook.sh    # 34 adapter tests (requires jq)

E2E tests

cd demo
bash test_e2e.sh     # 18 cross-language tests

Testing

Component	Tests	Framework
TypeScript	77	vitest
Python	71	pytest
Go CLI	~20	go test + race detector
Adapter	34	bash (test-hook.sh)
E2E	18	bash (test_e2e.sh)
Fuzz	21.9M inputs	go test -fuzz

Demo

# Quick trial — exercises the full pipeline
cd demo && bash trial.sh

# Full E2E test suite
cd demo && bash test_e2e.sh

See demo/README.md for details.

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