API Reference

Configuration options, types, and formats

BrowserLogsOptions

All options are optional with sensible defaults. Pass them to agentTail() (Vite) or withAgentTail() (Next.js).

logDirstringdefault: "tmp/logs"

Directory for log storage, relative to project root

logFileNamestringdefault: "browser.log"

Log file name within each session directory

maxLogSessionsnumberdefault: 10

Maximum number of log session directories to retain

endpointstringdefault: "/__browser-logs"

Server endpoint path for receiving log batches

flushIntervalnumberdefault: 500

Client-side flush interval in milliseconds

maxBatchSizenumberdefault: 50

Client-side max batch size before immediate flush

maxSerializeLengthnumberdefault: 2000

Max character length for serialized objects in client

warnOnMissingGitignorebooleandefault: true

Warn in terminal if logDir is not in .gitignore

levelsstring[]default: ["log", "warn", "error", "info", "debug"]

Console methods to intercept

captureErrorsbooleandefault: true

Capture unhandled window errors

captureRejectionsbooleandefault: true

Capture unhandled promise rejections

excludesstring[]default: []

Patterns to exclude from logs. Plain strings are substring matches; strings starting with / are parsed as regex (e.g. /^HMR/i). Filtering runs both client-side and server-side.

CLI commands

agent-tail run

Spawn one or more commands with unified logging. Each argument is a name: command pair:

agent-tail run 'fe: npm run dev' 'api: uv run server' 'worker: uv run worker'

Creates a session directory, spawns all services, prefixes output with [name], and writes individual + combined log files.

agent-tail wrap

Wrap a single command and write its output to a named log file in the current session:

agent-tail wrap server -- npm run dev

Useful when you want to add a service to an existing session created by agent-tail init or a framework plugin.

agent-tail init

Create a new log session directory without running any commands:

agent-tail init

Sets up the session directory and latest symlink. Useful when other tools (like framework plugins) will write to the session.

CLI options

Shared options for agent-tail run, agent-tail wrap, and agent-tail init:

--log-dir <dir>

Log directory relative to cwd (default: tmp/logs)

--max-sessions <n>

Max sessions to keep (default: 10)

--no-combined

Don't write to combined.log

--exclude <pattern>

Exclude lines matching pattern (repeatable). Plain strings are substring matches; strings starting with / are parsed as regex. Filters log content — matching lines are not written to any log file.

--mute <name>

Mute a service by name from terminal output and combined.log (repeatable). The service still runs and logs to its individual <name>.log file. Only applies to agent-tail run.

LogEntry type

interface LogEntry {
    level: string
    args: string[]
    timestamp: string
    url?: string
    stack?: string
}

This is the shape of each log entry sent from the browser to the dev server via the sendBeacon API.

Log format specification

[HH:MM:SS.mmm] [LEVEL  ] message (url)
    stack trace line 1
    stack trace line 2

The level field is padded to 7 characters for alignment. Stack traces are indented with 4 spaces. The URL is only included for errors that have source location info.

Directory structure

your-project/
├── tmp/
│   └── logs/
│       ├── 2024-01-15T10-30-00-123Z/
│       │   ├── browser.log
│       │   ├── api.log
│       │   ├── worker.log
│       │   └── combined.log
│       ├── 2024-01-15T11-45-00-456Z/
│       │   └── browser.log
│       └── latest -> 2024-01-15T11-45-00-456Z/
└── vite.config.ts

The latest symlink is updated atomically on each new session. Individual service log files are created by agent-tail run or agent-tail wrap. The combined.log contains all output interleaved with [name] prefixes.