looptail for AI agents

You are an AI agent (or you are building one). This page is written for you: exact commands, no marketing. Raw markdown version of this page: https://looptail.ai/docs/agents.md · site map for LLMs: https://looptail.ai/llms.txt · full facts: https://looptail.ai/llms-full.txt.

looptail records every AI decision as a hash-chained, Ed25519-signed, append-only trail — an audit trail your work can be verified against later. It is local-first: no account, no API key, no network required to start. Everything below works offline.

Start recording in three steps

TypeScript / Node (≥ 18):

npm install @looptail/sdk

import { Looptail } from '@looptail/sdk';

const lt = new Looptail({ app: 'my-agent' });

// wrap the function where a decision happens
export const decide = lt.trail(async (input) => {
  // ... your agent logic ...
});

// or record any loop event directly
lt.event('observe', { input: 'question', output: 'answer' });

Python (≥ 3.9):

pip install looptail

import looptail

looptail.init(app="my-agent")

@looptail.trail
def decide(input):
    ...

# or record any loop event directly
looptail.event("observe", {"input": "question", "output": "answer"})

Events append to .looptail/<app>.jsonl in the working directory. A signing key is created at ~/.looptail/signing-key on first use (never commit it; it is created outside the repo by default). Add .looptail/ to .gitignore unless the trail should ship with the repo.

Verify the chain

npx @looptail/cli verify --app my-agent

Exit code 0 = chain intact and signatures valid; 1 = verification failed; 2 = usage error. Add --json for machine-readable output. Any modification, reorder, or deletion inside the chain is detectable locally; truncation of the newest records is only detectable against hosted receipts (verify --anchors, needs an API key). Trails are cross-language: a trail written by the Python SDK verifies with the JS CLI and vice versa (open spec: https://github.com/maxfain/looptail/blob/main/spec/trail-format.md).

Event kinds

One vocabulary, six kinds — observe, evaluate, issue, improve, approve, outcome. Record with lt.event(kind, body, ref?) / looptail.event(kind, body, ref=None); ref links an event to an earlier event’s id. Report outcome signals with lt.outcome(eventId, { csat: 5 }) / looptail.outcome(event_id, csat=5).

Auto-instrument provider calls

Wrap a client once; every call becomes a signed observe event:

import { instrumentAnthropic, instrumentOpenAI } from '@looptail/sdk';
const anthropic = instrumentAnthropic(new Anthropic(), lt);

looptail.instrument.anthropic(client)  # or looptail.instrument.openai(client)

The whole loop (evals → issues → improve)

Both SDKs ship the full loop; each step is a signed event:

# score recorded events against a rubric you write (LLM judge)
npx @looptail/cli evals run --rubric rubric.json --app my-agent --judge anthropic:claude-opus-4-8

# cluster failing verdicts into tracked issues
npx @looptail/cli issues cluster --app my-agent

# draft a prompt patch from an issue, replay a regression set, approve — gated
npx @looptail/cli improve propose --app my-agent --issue <key> --prompt-file prompt.txt
npx @looptail/cli improve replay  --app my-agent --proposal <id> --cases cases.jsonl --runner mod:fn --rubric rubric.json
npx @looptail/cli improve approve --app my-agent --proposal <id> --apply

A rubric is JSON: {"name": "...", "version": 1, "criteria": ["..."], "pass_threshold": 0.85}. Judges use a provider:model spec — anthropic:<model> or openai:<model>; proposers are anthropic:<model> only for now. The provider SDK is an optional peer dependency, and the provider API key comes from the standard env var (ANTHROPIC_API_KEY / OPENAI_API_KEY). Python equivalents: looptail-evals, looptail-issues, looptail-improve.

Evidence export

npx @looptail/cli export --app my-agent --out evidence.zip

Writes a dated, self-verifying evidence pack (full chain, manifest, recipient-runnable verification instructions). Refuses to export a broken chain.

Hosted sync (optional)

With an API key, events also sync to the hosted Tail (re-verified server-side, anchored with signed receipts) — best-effort, never blocking, local trail remains the source of truth:

const lt = new Looptail({ app: 'my-agent', apiKey: process.env.LOOPTAIL_API_KEY });

Get a key: the Team plan is self-serve at https://looptail.ai/pricing (Scale and Enterprise: hello@looptail.ai), or request a private-beta invite programmatically:

curl -X POST https://ingest.looptail.ai/v1/waitlist \
  -H 'content-type: application/json' \
  -d '{"email": "you@example.com", "note": "agent integration", "source": "docs-agents"}'

Environment variables

Variable	Effect
LOOPTAIL_API_KEY	enables hosted sync + hosted evals
LOOPTAIL_TRAIL_DIR	trail directory (default ./.looptail)
LOOPTAIL_SIGNING_KEY	hex Ed25519 seed; overrides the key file
LOOPTAIL_ACTOR	who approves (improve approve provenance)

Rules of the trail

• The trail is append-only. Never edit .looptail/*.jsonl by hand — that breaks the chain, and verification will say so.
• The local trail is written before any network call; hosted sync failures never raise into the app.
• The trail format is an open, versioned spec. Current packages: @looptail/sdk, @looptail/cli (npm), looptail (PyPI).

Claude Code users: /plugin marketplace add maxfain/looptail installs a skill that teaches the agent to do all of the above in the current project.