agent-tail
Pipes browser console output and dev server stdout/stderr to plain log files on disk so you can grep, tail, and read them directly.
Reading logs
agent-tail tail -n 200
agent-tail tail browser -n 50
agent-tail tail -f
grep -ri "error\|warn" tmp/logs/latest/
tail -50 tmp/logs/latest/browser.log
tail -f tmp/logs/latest/*.log
Use plain tail if direct file paths are easier. Use agent-tail tail if you want the CLI to resolve the latest session for you and forward flags like -f and -n 200 directly to tail.
Log files
Logs live in tmp/logs/latest/ (a symlink to the newest session directory, stable across restarts):
| File | Source |
|---|---|
browser.log | Browser console.*, unhandled errors/rejections (Vite or Next.js plugin) |
<name>.log | stdout/stderr of a named service (CLI) |
combined.log | All services interleaved, prefixed with [name] (CLI) |
Log format
[HH:MM:SS.mmm] [LEVEL ] message (source-url)
stack trace indented with 4 spaces
Levels are uppercased and padded to 7 characters (LOG , WARN , ERROR ).
CLI
agent-tail run 'fe: npm run dev' 'api: uv run server' # run multiple services
agent-tail wrap api -- uv run fastapi-server # add to existing session
agent-tail init # create session only
tail -f tmp/logs/latest/*.log # tail directly by path
agent-tail tail -f # tail all logs in latest session
agent-tail tail browser -n 50 # tail one log in latest session
Flags (work with all commands):
--log-dir <dir> Log directory (default: tmp/logs)
--max-sessions <n> Max sessions to keep (default: 10)
--no-combined Don't write combined.log
--exclude <pattern> Exclude lines matching pattern (repeatable, /regex/ or substring)
--mute <name> Mute service from terminal + combined.log (still logs to <name>.log)
See references/cli-reference.md for full details.
Setup
npm install -D agent-tail
- CLI (any stack): Add
agent-tail run 'name: command'to your dev script - Vite: See
references/setup-vite.md - Next.js: See
references/setup-nextjs.md(config wrapper + layout script + API route)
Agent instructions
Add to your project's CLAUDE.md, .cursorrules, 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
.gitignore
Add tmp/ to .gitignore. agent-tail warns on startup if the log directory isn't gitignored.