Twilic AI
Record, replay, and inspect AI streams and agent runs as Twilic binary sessions.
Record once. Replay anywhere. Send less.
Twilic AI turns streaming LLM and agent traffic into compact, replayable .twai sessions. Use it to shrink traces for storage and transport, compare runs, and debug with the same CLI tooling as the rest of Twilic.
Source: github.com/twilic/ai
Packages
| Package | Role | Docs |
|---|---|---|
@twilic/ai | Core recorder, .twai codec, replay, inspect, diff | Core |
@twilic/ai-openai | OpenAI Responses API event normalization | OpenAI |
@twilic/ai-sdk | Vercel AI SDK transport + recorder helpers | AI SDK |
@twilic/ai-agents | Agents SDK tracing processor | Agents |
Install
pnpm add @twilic/ai @twilic/coreOptional adapters:
pnpm add @twilic/ai-openai @twilic/ai-sdk @twilic/ai-agentsFor CLI session tooling:
pnpm add -g @twilic/cli @twilic/core @twilic/aiQuick start
import { createAIRecorder, ensureTwilicInit, writeSession } from "@twilic/ai";
await ensureTwilicInit();
const recorder = createAIRecorder({
sessionId: "demo-session",
meta: { provider: "openai", model: "gpt-4.1" },
});
await recorder.record(async () => {
recorder.append({
type: "text.delta",
sequence: recorder.events.length,
timestamp: Date.now(),
sessionId: "demo-session",
data: { delta: "Hello from Twilic AI." },
});
});
await writeSession("session.twai", {
meta: {
format: "twai",
version: 1,
sessionId: "demo-session",
createdAt: Date.now(),
eventCount: recorder.events.length,
},
events: recorder.events,
});Inspect and replay with the CLI:
twilic ai inspect session.twai
twilic ai replay session.twai --speed 10
twilic ai record --input events.jsonl -o session.twai.twai sessions
.twai is the canonical container for Twilic AI sessions. It stores Twilic-encoded session metadata and a ordered list of canonical AI events.
| Field | Description |
|---|---|
| MIME type | application/vnd.twilic.ai+twai |
| Extension | .twai |
| Magic | ASCII TWAI |
Each event includes type, sequence, timestamp, sessionId, optional correlation IDs (responseId, itemId, toolCallId), and a data payload. Canonical types include text.delta, reasoning.delta, tool.started, tool.output, response.completed, and more.
See the .twai format page for the on-disk layout.
When to use it
| Goal | Approach |
|---|---|
| Persist a chat or agent run | Record events → write .twai |
| Shrink traces vs JSON/JSONL | Encode with @twilic/ai; compare with twilic ai benchmark |
| Normalize provider streams | @twilic/ai-openai for OpenAI Responses |
| Capture Vercel AI SDK chats | TwilicChatTransport from @twilic/ai-sdk |
| Trace Agents SDK runs | TwilicTracingProcessor from @twilic/ai-agents |
| Diff two runs | diffSessions or twilic ai diff |