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';constevents=parseTrace(traceContent);constmetrics=computeMetrics(events);console.log(`Iterations: ${metrics.totalIterations}, Cost: $${metrics.totalCostUsd}`);

Parse traces (Python)

pip install loopeng-ltf

fromltfimportparse_trace, compute_metricsevents=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 sourcecd 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 pipelinecd demo && bash trial.sh
# Full E2E test suitecd 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