mcpField
A
agent-tail

agent-tail

github.com/gillkyleDevelopment9365 installsUpdated 33w ago
Repository

About agent-tail

agent-tail is a CLI that captures browser console output and development-service stdout and stderr in plain log files. It helps developers and coding agents inspect runtime issues with familiar log-reading tools.

Key features

  1. 01Capture browser console messages and errors
  2. 02Save service stdout and stderr
  3. 03Combine logs from multiple services
  4. 04Tail logs by session or service
  5. 05Filter lines and mute terminal output

Use cases

  1. 01Inspect browser errors during development
  2. 02Review output from several dev services
  3. 03Follow the latest session's logs
  4. 04Search logs for warnings and errors

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/gillkyle/agent-tail --skill agent-tail

After installing, type/agent-tailin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
cli-reference.md
setup-nextjs.md
setup-vite.md

Details

From the project README

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):

FileSource
browser.logBrowser console.*, unhandled errors/rejections (Vite or Next.js plugin)
<name>.logstdout/stderr of a named service (CLI)
combined.logAll 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.

Comments

Markdown supported