dev-log

dev-log

Collect runtime logs in real time to a local service via HTTP requests, and let AI read and analyze them on its own—no screenshots, no copying console output. AI handles instrumentation, the user handles the operations, and AI handles reading the logs.

When to use

Proactively use it in the following scenarios:

1. The frontend code you generate may need debugging / verification.
2. The user says "take a look for me," "there's a problem," or "check why."
3. You need to trace asynchronous flows (fetch, Promise, async/await).
4. You need to see runtime values of variables (especially user input or dynamically computed values).

Do not use for: purely static content, trivial one-off checks, or purely backend (Node server-side) code—for the latter, just look at stdout.

Commands

All operations are done through a single CLI, invoked with npx @dev-log/cli .

Tip: The first npx execution will show an install confirmation (Ok to proceed?), and the agent will get stuck when executing automatically. It is recommended to add -y to skip it:npx -y @dev-log/cli <command>. The examples below omit -y。

npx @dev-log/cli start                            # 启动日志服务（端口 7331，后台 daemon）
npx @dev-log/cli gen --lang <lang> [options]      # 生成可直接粘贴的日志语句
npx @dev-log/cli logs [--session <id>]            # 读取已收集的日志
npx @dev-log/cli clear [--session <id>]           # 清除日志（不传 --session 清全部）
npx @dev-log/cli status                           # 查看服务状态
npx @dev-log/cli tunnel                           # 可选：启动 HTTPS 隧道（HTTPS 页面 / 远程访问）
npx @dev-log/cli stop                             # 停止服务
npx @dev-log/cli --help                           # 查看所有命令和选项

gen options

Option	Description
--lang <lang>	Target language:js ts python go swift kotlin dart cpp rust java csharp php ruby
--type <type>	Log type — state(default),error、validation、click、request , etc.
--data <expr>	Data payload, using a literal/expression in the target language (e.g. {count:1}）
--ready	Generate __ready__ connectivity probe, not a business log
--session <id>	Reuse sessionId (default: generate a new sess_xxxxxxxx）
--url <url>	Endpoint URL (default:http://localhost:7331）

gen Only output codeto stdout—capture it and insert it into the user's source code. It automatically injects sessionId, timestamp expressions, and (when using --ready )__ready__ probe.

Workflow

1. Start the service

npx @dev-log/cli start

start will fork abackground daemonand return immediately—no need for nohup, no need for &, and the foreground does not block. The daemon survives independently of the agent/child process. Confirm it has started:

sleep 2 && npx @dev-log/cli status

2. Choose a session id and instrument

Key: For each debugging target, chooseone sess_xxxxxxxx, and onevery gen call pass in the same. If you do not pass --session and call gentwice in a row, you will get two different random ids, and the logs will be split across different sessions—losing their meaning. Always pass --session <同一个 id>。

First generate a connectivity probe, then generate business logs:

# 连通性探测（始终第一个）
npx @dev-log/cli gen --lang js --ready --session sess_a1b2c3d4

# 业务日志
npx @dev-log/cli gen --lang js --type state --data '{count: count}' --session sess_a1b2c3d4
npx @dev-log/cli gen --lang js --type error --data '{msg: err.message}' --session sess_a1b2c3d4

Insert each piece of output code into the corresponding location in the user's source code.

Mobile / HTTPS pages: The default http://localhost:7331 only applies to local HTTP pages. For HTTPS pages, mobile devices, or remote machines, you need to start a tunnel and pass in --url：

npx @dev-log/cli tunnel          # 输出 https://xxxx.loca.lt
npx @dev-log/cli gen --lang js --ready --session sess_a1b2c3d4 --url https://xxxx.loca.lt

3. Ask the user to operate

Tell the user: "I have added logs at the key locations, please operate."

4. Read and analyze the logs

When the user says "done," read the logs (be sure to filter by your session id to avoid reading data from other sessions):

npx @dev-log/cli logs --session sess_a1b2c3d4

Diagnose based on the __ready__ probe:

__ready__ whether it exists	Diagnose
✅ Exists, and has business logs	Analyze business logs — Done.
✅ Present, butnobusiness logs	The probe reached the service, but the instrumentation code did not execute. Check event binding / trigger conditions / whether the user actually performed the action.
❌ No probe at all	Network: the page cannot connect to the service. It may be an HTTPS page requesting an HTTP endpoint (MIXED_CONTENT) — switch to a tunnel URL.

Session Cleanup

Services are shared across sessions. Never kill a service or clearjust because a conversation ends (without --session）。

When a debugging goal is complete:

npx @dev-log/cli clear --session sess_a1b2c3d4     # 只清除本会话的日志
npx @dev-log/cli status                            # 是否还有其他活跃会话？

Only when status shows zero active sessions should you stop the service:

npx @dev-log/cli stop

Security

• Never log sensitive information. When data contains credentials, filter sensitive fields before logging.
• Sensitive field names (case-insensitive):password、pwd、token、secret、apikey、key、credit、cvv、ssn、auth。

// 记录前剥离敏感字段
const safe = (o) => {
  const k = ['password','pwd','token','secret','key','credit','cvv','ssn','auth'];
  return Object.fromEntries(Object.entries(o).map(([n,v]) =>
    [n, k.some(s => n.toLowerCase().includes(s)) ? '***' : v]));
};

Notes

1. The service writes logs and the PID to $TMPDIR/dev-log/(the system temporary directory) — the installed package directory stays clean.
2. Fixed port 7331; no random port, no need to read a port file.
3. start runs as a background daemon — no need for nohup/&. Use npx @dev-log/cli stop to stop.
4. Be sure to remove all debugging instrumentation code before release.
5. Local development only — do not expose to the public internet.