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.

1. Install the CLI

Global install:

npm install -g agent-tail

Project install:

npm install -D agent-tail

Global install gives you agent-tail directly in your shell. Project install works with npx agent-tail or package scripts. In both cases, logs still go to tmp/logs/ relative to the project by default.

If you prefer a hidden folder, use --log-dir .agent-tail for the CLI and logDir: ".agent-tail" for the framework plugin config.

2. Wrap your dev command

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'

3. Tail the logs

Use plain tail if you want direct file paths, or use agent-tail tail if you want the CLI to resolve the latest session for you and forward the flags unchanged.

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

agent-tail tail -f
agent-tail tail browser -n 50

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
# or
agent-tail tail browser -f

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

Install the agent-tail skill to give your AI coding agent built-in knowledge of how to set up and use agent-tail:

npx skills add gillkyle/agent-tail

The skill activates automatically when you ask about capturing logs, debugging runtime errors, or checking console output. Works with Claude Code, Cursor, Codex, and other supported agents.

Or add a snippet to your project's agent instructions file manually (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:

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