FAQ

In bash, >> appends stdout to a file and &>> appends both stdout and stderr to a file. That's exactly what agent-tail does — captures all output (stdout, stderr, browser console, unhandled errors) and appends it to log files on disk. We use &>> as the project's symbol.

agent-tail captures server output and browser console logs to plain text files on disk during development. The CLI wraps any command to capture stdout/stderr, and framework plugins for Vite and Next.js capture browser console.* calls. You can tail -f them in your terminal, and AI coding agents that already know how to read files and use grep can access them directly.

There are dedicated plugins for Vite (import from agent-tail/vite) and Next.js (import from agent-tail/next). The CLI works with any dev server command.

By default: console.log, console.warn, console.error, console.info, and console.debug. You can customize this with the levels option. Additionally, unhandled errors (window.onerror) and unhandled promise rejections are captured by default.

Use agent-tail run or agent-tail wrap to capture stdout/stderr from any command. Or point your server's logging directly at tmp/logs/latest/. The README has examples for Python, Node.js, Ruby, and Go.

CLI: stdout and stderr from any command.

Plugins: console.log, console.warn, console.error, console.info, and console.debug.

Unhandled errors (window.onerror) — logged as UNCAUGHT_ERROR.

Unhandled promise rejections — logged as UNHANDLED_REJECTION.

Plain log files beat a protocol server for this use case:

Universal — works with any agent, any editor, tail, grep, awk. MCP only works with agents that explicitly support it.

No moving parts — appendFile() vs. a server process + protocol + tool registration + connection lifecycle.

Zero connection state — the file is a persistent timeline, not a live stream you can miss.

Composable — pipe through grep, chain with awk, redirect to another file. MCP tool results have to pass through the agent's context window.

Token efficient — reading a file costs nothing in tool descriptions. MCP servers use 13–18k tokens just in tool definitions.

Deterministic for agents — "read the last 200 lines of tmp/logs/latest/browser.log" beats hoping the model calls a tool correctly.

That said, MCP has real strengths in other contexts — structured, queryable interfaces for complex data sources, or environments where the agent has no filesystem access.

No, and it's not designed to. agent-tail is a development tool. The injected client script only activates in development mode. For production logging, use a proper observability stack.

Each dev server start creates a new timestamped directory (e.g. 2024-01-15T10-30-00-123Z/) under your log directory. A latest symlink is updated to point to the newest session. Old sessions beyond maxLogSessions are automatically pruned.

Yes! This is a core feature. Use agent-tail run to start everything from one command, or use agent-tail wrap to add services to an existing session. Each service gets its own log file, plus a combined.log with everything interleaved.

Install agent-tail — it's the umbrella package that includes the CLI, Vite plugin, and Next.js plugin. One install, all features: npm install -D agent-tail.

Yes. If you only need one piece, you can install it directly:

agent-tail-core — CLI only (agent-tail run, agent-tail wrap, agent-tail init). Import from "agent-tail-core".

vite-plugin-agent-tail — Vite plugin only. Import from "vite-plugin-agent-tail".

next-plugin-agent-tail — Next.js plugin only. Import from "next-plugin-agent-tail", "next-plugin-agent-tail/script", "next-plugin-agent-tail/handler".

The umbrella agent-tail package re-exports everything from these packages, so you only need one install.

Make sure your dev server is running and you're visiting a page in the browser. Check that the plugin is correctly configured in your build config. Look for the /__browser-logs endpoint being registered in your dev server output.

Either add tmp/ to your .gitignore (recommended) or set warnOnMissingGitignore: false in the plugin options.

Open an issue on GitHub.