agent-tail

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

将浏览器控制台输出及开发服务器的stdout/stderr输出写入磁盘上的纯文本日志文件，方便你直接使用

grep

、

tail

命令查看或检索日志。

Reading logs

查看日志

bash

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

bash

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

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)

日志存储在

tmp/logs/latest/

目录下（该目录是指向最新会话目录的符号链接，重启后仍保持稳定）：

文件	来源
`browser.log`	浏览器 `console.*` 输出、未处理的错误/拒绝（Vite或Next.js插件捕获）
`<name>.log`	命名服务的stdout/stderr输出（CLI模式）
`combined.log`	所有服务的日志合并输出，每条日志前缀为 `[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

[HH:MM:SS.mmm] [LEVEL  ] message (source-url)
    stack trace indented with 4 spaces

日志级别为大写格式，且填充至7个字符长度（如

LOG

、

WARN

、

ERROR

）。

CLI

命令行界面（CLI）

bash

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

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.

bash

agent-tail run 'fe: npm run dev' 'api: uv run server'   # 运行多个服务
agent-tail wrap api -- uv run fastapi-server              # 加入现有会话
agent-tail init                                           # 仅创建会话

参数（适用于所有命令）：

--log-dir <dir>       日志目录（默认：tmp/logs）
--max-sessions <n>    保留的最大会话数（默认：10）
--no-combined         不生成combined.log
--exclude <pattern>   排除匹配指定规则的日志行（可重复使用，支持正则/regex/或子字符串）
--mute <name>         屏蔽指定服务的终端输出及combined.log记录（仍会写入<name>.log）

完整详情请查看

references/cli-reference.md

。

Setup

安装配置

bash

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)

bash

npm install -D agent-tail

CLI（任意技术栈）： 在你的开发脚本中添加
```
agent-tail run 'name: command'
```
Vite： 请查看
```
references/setup-vite.md
```
Next.js： 请查看
```
references/setup-nextjs.md
```
（包含配置包装器、布局脚本及API路由）

Agent instructions

Agent使用说明

Add to your project's

CLAUDE.md

.cursorrules

, or equivalent:

markdown

undefined

将以下内容添加到项目的

CLAUDE.md

、

.cursorrules

或同类文件中：

markdown

undefined

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

undefined

所有开发服务器输出都会被捕获到

tmp/logs/

目录下。最新的会话日志通过符号链接指向

tmp/logs/latest/

。

调试时，请先查看日志，再推测运行时行为：

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

undefined

.gitignore

Git忽略配置

Add

tmp/

.gitignore

. agent-tail warns on startup if the log directory isn't gitignored.

将

tmp/

添加到

.gitignore

文件中。如果日志目录未被Git忽略，agent-tail启动时会发出警告。