agentvu

Watch your AI agent think, live, in a beautiful terminal dashboard.

agentvu is a tiny library + CLI that records an AI agent's run as a stream of structured events and visualizes it as a gorgeous terminal dashboard — a timeline of model calls, tool calls (with args and results), tokens, cost and durations. Replay a finished run, or follow it live as it happens.

• 1-line integration with the Vercel AI SDK — drop recordStep into onStepFinish.
• Zero lock-in — events are plain JSON, one per line (JSONL). No service, no SDK to learn, no network.
• Live or replayed — --follow tails the file and renders new events as your agent runs.
• Cost & tokens — built-in (approximate) price table for popular models.

Install

# global CLI
npm install -g agentvu

# or as a project dependency / library
pnpm add agentvu

Requires Node.js >= 18.

Visualize a session

agentvu examples/session.jsonl

agentvu session.jsonl
steps 3  tools getWeather,getForecast  tokens 1996  cost $0.02  dur 3.0s

▍ user What's the weather in Tokyo and should I bring an umbrella?
◆ gpt-4o system + user: weather question for Tokyo (820ms)
→ getWeather {"city":"Tokyo","units":"metric"}
← getWeather {"tempC":18,"condition":"light rain",...} (260ms)
∑ usage 412 in / 86 out (gpt-4o)
...

Live demo (--follow)

Point agentvu at the file your agent is writing and watch it think in real time:

agentvu session.jsonl --follow

It tails the file and re-renders the dashboard every time a new event is appended.

JSON output

agentvu session.jsonl --json   # parsed events + a computed summary

Record a session

1-line Vercel AI SDK integration

import { generateText } from "ai";
import { createRecorder, recordStep } from "agentvu";

const rec = createRecorder({ out: "session.jsonl" });

await generateText({
  model,
  prompt: "What's the weather in Tokyo?",
  tools,
  maxSteps: 5,
  onStepFinish: (step) => recordStep(rec, step), // ← that's it
});

rec.close();

Then, in another terminal:

agentvu session.jsonl --follow

recordStep only depends on the shape of the AI SDK step — agentvu does not import the ai package, so it stays dependency-light.

Recording API

createRecorder({ out?, now? }) returns a recorder. Each method records one event (and, when out is set, appends one JSONL line):

import { createRecorder } from "agentvu";

const rec = createRecorder({ out: "session.jsonl" });

rec.message({ role: "user", text: "Find me a flight." });
rec.model({ model: "gpt-4o", prompt: "plan the search", durationMs: 740 });
rec.toolCall({ name: "searchFlights", args: { from: "ADD", to: "NRT" } });
rec.toolResult({ name: "searchFlights", result: { count: 12 }, durationMs: 310 });
rec.usage({ inputTokens: 540, outputTokens: 120, model: "gpt-4o" });
rec.error({ message: "rate limited" });

rec.events;   // the in-memory event array
rec.close();  // flush / finish

Recording is pure and synchronous; the only side effect is an isolated, append-only write to out.

Event model

Every event is JSON-serializable and carries ts (epoch ms) plus a type discriminator:

| type | fields | | ------------- | -------------------------------------------------- | | message | role, text | | model | model, prompt, durationMs? | | tool-call | name, args | | tool-result | name, result, durationMs? | | usage | inputTokens, outputTokens, model? | | error | message |

Cost

import { costOf } from "agentvu";

costOf({ inputTokens: 540, outputTokens: 120, model: "gpt-4o" }); // ≈ USD

costOf uses a small, approximate built-in price table (USD per 1M tokens) for popular models (gpt-4o, gpt-4o-mini, claude-3.5-sonnet, …). Unknown models cost 0. Prices drift — treat the numbers as a ballpark, not billing.

Library exports

import {
  createRecorder, recordStep,        // record
  parseJsonl, encodeEvent, isAgentEvent,
  summarize, costOf, priceOf, PRICES,
  formatDuration, formatCost, compactValue,
} from "agentvu";
import type { AgentEvent, Recorder, AiSdkStep, SessionSummary } from "agentvu";

License

MIT © 2026 Abdulmunim Jemal