Quick start

agentwatch has two halves: a library that records your agent’s run to a JSONL file, and a CLI that visualizes that file as a dashboard. This guide takes you through both.

1. Install

# the CLI, globally
npm install -g agentwatch

# or as a project dependency / library
pnpm add agentwatch
# npm install agentwatch · yarn add agentwatch

Requires Node.js ≥ 18.

2. Visualize the bundled example

You don’t need an agent to see what agentwatch does. Point it at the example session that ships with the repo:

agentwatch examples/session.jsonl

agentwatch 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)
...

The header line summarizes the whole run; each row below is one event in the order it happened.

3. Record your own run

The 1-line Vercel AI SDK integration

If you use the Vercel AI SDK, wiring in agentwatch is a single line. Create a recorder pointed at an output file, then hand each step to recordStep from the SDK’s onStepFinish callback:

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

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();

recordStep translates each AI SDK step into agentwatch events — assistant text, tool calls, tool results, and usage — and appends them to session.jsonl. It only depends on the shape of the step object, so agentwatch never imports the ai package and stays dependency-light.

Or write events by hand

Not on the AI SDK? Record events directly. Each recorder method writes one JSONL line:

import { createRecorder } from "agentwatch";

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.close();

Either way you end up with a session.jsonl — a plain file you can replay, commit, or pipe somewhere else.

4. Watch it live

In one terminal, run your agent (writing to session.jsonl). In another, follow the file:

agentwatch session.jsonl --follow

agentwatch tails the file and re-renders the dashboard every time a new event is appended — so you watch the agent think in real time. Press Ctrl+C to stop.

What next?

• Recording — the full event model, every recorder method, the AI SDK adapter, and cost estimation.
• CLI — every flag, exit codes, and --json output.
• API — the complete exported library surface.