Installation

agent-tail captures two kinds of logs: server-side output (stdout/stderr from your dev commands) and client-side output (browser console.* calls). The CLI handles server logs and works with any stack. Framework plugins for Vite and Next.js handle browser logs. Use them together to get everything in one place.

CLI (server-side logs)

The CLI wraps any command and captures its stdout/stderr to log files. No plugins, no config — works with any language or framework.

npm install -D agent-tail

agent-tail run

Wrap one or more commands with unified logging:

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

It works with any command, not just Node — Python, Go, Ruby, whatever you run in a terminal:

npx agent-tail run 'api: uv run fastapi dev'

Vite plugin (browser logs)

The Vite plugin captures browser console.* calls by injecting a small script into your page during development. Logs are written to browser.log in the same session directory the CLI uses.

npm install -D agent-tail

Then in another terminal:

tail -f tmp/logs/latest/browser.log

Next.js plugin (browser logs)

The Next.js plugin does the same thing — captures browser console.* output — but requires a bit more wiring because of how Next.js handles config, layouts, and API routes.

npm install -D agent-tail

1. Wrap your Next.js config

2. Add the script to your layout

3. Create the API route

// app/api/__browser-logs/route.ts
export { POST } from "agent-tail/next/handler"

.gitignore setup

Add your log directory to .gitignore:

# .gitignore
tmp/

agent-tail warns on startup if the log directory isn't gitignored. Disable with warnOnMissingGitignore: false.

Agent setup

Optional. You can always point your agent at the logs manually, but adding a snippet to your instructions file means it checks logs automatically — before asking you what went wrong.

Add a section to your project's agent instructions file (CLAUDE.md, .cursorrules, .github/copilot-instructions.md, or equivalent):

## Dev Logs

All dev server output is captured to `tmp/logs/`. The latest session
is symlinked at `tmp/logs/latest/`.

When debugging, check logs before guessing about runtime behavior, ie:

    grep -ri "error\|warn" tmp/logs/latest/
    tail -50 tmp/logs/latest/browser.log

That's all. The agent now knows where runtime truth lives and can read logs instead of asking you to describe what went wrong.