智能体尾随台 ionut27001/agenttail

agenttail

给 AI 编程智能体用的 tail -f —— 一块实时仪表盘，同时看 DeepSeek Harness、Claude Code 和 Antigravity 的会话，dsh 还能选择开启控制。由 Tail 守着，就是那个带眼睛的折线箭头。

官网 ·下载 ·快速开始 ·认识 Tail ·监控墙 ·主题 ·流模式 ·安全

去官网看实时演示：一段回放的会话、可以上手的 Tail、它全部十款小游戏和主题，都在浏览器里。

agenttail 跟着编程智能体本来就在写的会话日志走，把它们汇成一块安静的仪表盘：正在编辑的文件、正在运行的命令、智能体对话、活动状态，全是实时的。默认只读，绝不写入智能体的会话存储、工作区或对话记录。加上 --allow-control 参数后，它也能启动并驱动自己的 DeepSeek Harness 会话。

[!NOTE]
默认只读；控制功能需手动开启，并有 token 保护。只监听本机，无遥测。agenttail 是独立项目，与 DeepSeek、Anthropic、Google 均无关联。

它是什么

一个零运行时依赖的 Node 24 服务，加一个单页 UI。它读取本地日志，统一成同一种事件结构，通过 SSE 推流，再渲染到 127.0.0.1 上。流模式会在任何内容到达浏览器之前，先抹掉密钥和身份信息。

支持的数据源

| 数据源 | 读取的日志 | 监控 | 可从 agenttail 驱动 | 需要你介入 |
| DeepSeek Harness | ~/.dsh/sessions//session.v4.jsonl.zstd | 16 项中 6 项完整，10 项部分 | 可以，走 ACP：7 项中 4 项 | 权限提示（日志）；额度用尽和未登录 |
| Claude Code | ~/.claude/projects//.jsonl，外加 ~/.claude/sessions/.json 的状态字段 | 16 项中 3 项完整，13 项部分 | 尚未支持（计划 0.5 版本） | 权限与输入提示词（状态文件），问题与计划（transcript） |
| Antigravity CLI | ~/.gemini/antigravity-cli/ | 16 项中 1 项完整，12 项部分 | 尚未支持 | 权限提示词，来自 CLI 日志 |
| Antigravity 编辑器 | ~/.gemini/antigravity/ | 16 项中 1 项完整，11 项部分 | 没有可驱动的接口 | 无：它不写 agenttail 能读的信号 |

每个来源都按同一份清单核对：16 个监视项、7 个驱动项。docs/dev/harness-coverage.md 里有逐项矩阵、证据和缺口说明。「完整」指已实现且有测试覆盖；在真实安装上的实测记录见 docs/dev/verification-log.md。只列出日志在本地存在的会话；空会话藏在选择器的开关后面。Needs you 的说明见下文。

来源适配器详情

- DeepSeek Harness 从 ~/.dsh/sessions 读取 session.v4.jsonl.zstd 帧，用 Node 内置的 zlib 解码，能识别编辑、命令、后台任务、思考和 token 用量，包括压缩调用。服务商故障（余额不足、限流、超时、未登录）从失败的尝试、重试和最终放弃那一轮的报错中读出，在 Chat、Log 和控制台里显示为红色标签，措辞固定并附上 HTTP 状态码，绝不显示服务商自己的消息。每条回复按 DeepSeek 公布的自有服务商与模型列表价计价（deepseek-flash、deepseek-v4-pro，按高峰时段分档）；已登录的 deepseek-account 路由、Ollama 和其他模型只显示 token，因为它们没有公开的每 token 价格。页头把该数字称为列表价估算，附上价格表日期，并说明会话中哪部分没有价格。标题优先取本地昵称，其次取真实的 session/title（忽略从首个提示词派生的兜底标题），再次取最后一条真实用户消息（前 60 个字符），最后取首个提示词。
- Claude Code 读取 ~/.claude/projects 下的会话记录，包括自定义标题、思考块、工具调用、子代理和尚未落盘的实时写入。每条回复只计一次（Claude Code 会在每个内容块行上重复一条回复的用量）。一个回合从真实提示词开始，到 end_turn 结束，或因输出上限被截断的回复也算一个回合，回合里会标注为被截断。上下文压缩显示为一条细的「context compacted」行（记录里有 token 数时，会带上压缩前后的数量），不算提示词，也不算回合。回合运行期间你输入的提示词（Claude Code 会写成排队命令）只在其所属回合里显示一次，不会新开回合；在 Chat、Log 和控制台里，每条提示词都标注了作者，所以任务通知、其他智能体、SDK 或定时任务都不会显示成你写的。
每条回复都按其自身模型在 Anthropic API 的标价计价：包含缓存读取、5 分钟和 1 小时缓存写入、Haiku 5.5 的长提示词费率、Opus 5.5 快速模式和网页搜索。表头标为 ≈ API：订阅用户可拿它衡量这个会话做了多少工作，它不是你的账单。Claude Code 进程存活期间，其 ~/.claude/sessions/<pid>.json 里的状态字段（忙碌、空闲或等待，以及等待什么）决定实时状态和 needs-you 信号；只读取这些字段，旁边的 .key 文件从不打开。
- Antigravity 读取命令行（~/.gemini/antigravity-cli/brain）和编辑器（~/.gemini/antigravity/brain）的对话，统一整理消息、思考、工具调用和文件编辑。每个工具调用都连同自己的结果显示（包括 agenttail 没有专门视图的工具，比如搜索、列目录、网页抓取和子代理），失败和被拒绝的工具会标出来，Antigravity 留下仍在运行的命令显示为运行中。内容较长时，若存在 transcript_full.jsonl 就从那里读取。对命令行还会读取 ~/.gemini/antigravity-cli/log/cli-.log 用于 needs-you，只保留会话 id、步骤编号、工具名、进程 id 和时间。Antigravity 的数据库从不打开。
- 会话按实时优先排序，其次按最后活动时间。表头只显示短 id；选择器里带完整标题和详情。昵称存放在配置目录的 nicknames.json 里（绝不在 .dsh 里），和其他标签一样会被脱敏。

快速开始

1. 获取 agenttail。 从 Releases 下载 Windows exe，或运行：

npx github:ionut27001/agenttail

agenttail 还没上 npm registry；npx agenttail 以后才会有。

也可以从克隆的仓库运行：

npm install
npm start

2. 打开 http://127.0.0.1:8787。 服务器会自动帮你打开浏览器；加 --no-open 可关闭。PORT=9000 可改端口。
3. 选择会话。 最新的会话排在最前；空会话收在筛选器开关后面。

环境要求：Node 24+，Windows、macOS 或 Linux。Windows 是经过测试的平台；见限制。

功能

- ✍️ 编辑器实时打字 — 跟随智能体正在编辑的文件，在原位打出改动，并带一道短暂的高亮扫过。
- 🌡️ 编辑热度 — 文件树记录编辑、失败和删除的文件；悬停时显示 N edits · last … · M failed。除非开启 show hidden files，否则隐藏 .tmp、_、node_modules、.git 和构建目录。
- ⌨️ 控制台与任务进度 — 运行中的 spinner、已用时间、可折叠的多行命令、(+N lines) 输出、实时任务条和 [n/N] 迷你进度条。失败的命令闪红，并显示 ✗ COMMAND FAILED 三秒。
- 💬 Chat 与 Log — Chat 把工具调用和思考分组，方便阅读；Log 是完整轨迹，用于审计（MD 按钮可导出为 Markdown），每轮附一份摘要（模型、按类型统计的工具、改动的文件、失败、token、费用、耗时）。智能体的回复按 markdown 渲染：标题、列表、表格、引用、代码和链接。
- 🔔 Needs you — 每个来源都会告诉你智能体何时卡在等你：选择器里一个琥珀色圆点和 NEEDS YOU · permission · Bash，概览里一个标签，墙上一个琥珀色边框（该窗格永不缩小），标签页标题和 favicon 里一个计数，可选的桌面通知，以及一个收件箱汇总所有等待项。见 Needs you。
- 🛡️ 权限模式 — 每个会话都显示其智能体在不询问的情况下能做多少事，用 harness 自己的措辞加一个风险等级：安静的 ASKS、EDITS、REVIEWER、PLAN 或 REFUSES，以及醒目的红色 BYPASS。它出现在会话选择器、会话头部、智能体概览和每个监视墙窗格中；DeepSeek Harness 会话在运行中途切到 bypass 时，会在 chat、log 和控制台里各加一行告警。见权限模式。
- 👥 同时多个智能体 — 概览列出最近 30 分钟内活跃的每个智能体（dsh、Claude Code、Antigravity），按 git 仓库分组（worktree 算同一个仓库），各自带颜色、分支、模型和当前动作。活动栏列出你正在查看的仓库上的其他智能体，文件树标出它们编辑过的文件。Alt+W 打开监视墙。
- 🎭 控制台上台 — 智能体运行命令时，控制台升到编辑器上方；它编辑时，控制台回到停靠位；没有内容可展示时，它缩成一条细栏，把空间让给智能体窗格。从控制台头部可切回普通停靠式控制台。
- 🐾 Tail，吉祥物 — 活过来的 logo：它对智能体的动作做出反应，模型思考时它大声思考，长时间思考时它玩游戏。见认识 Tail。
- 🎨 主题 — 七款，从 matrix 到浅色纸张主题。见主题。
- ◉ 单一活动状态 —— RUNNING、EDITING、THINKING、REPLYING、IDLE 或 DONE，配一条色带和一个圆点；任务收尾时短暂显示对勾，随后回到当前状态。
- 🧮 上下文 —— 会话占用了模型上下文窗口的多少，显示在活动栏和每个墙面板上。
- 📊 仪表与布局 —— CPU、RAM、GPU、步数、token、每秒输出 token（30 秒平均值，带迷你折线图）和费用：对 DeepSeek Harness 按高峰时段估算目录价，每条回复按它自己的服务商和模型计价（模型没有公开价格时只算 token）；对 Claude Code 则按 Anthropic API 目录价折算这些 token 的花费（≈ API，即使订阅也能当参照）；控制台与聊天并排，或把智能体面板停靠为右侧通高栏（Ctrl+Shift+.）；可折叠侧栏，UI 缩放 90/100/115/130%（宽屏新配置档默认 115%）。重复的相同操作合并成一行控制台输出，并带计数。
- ⏪ 回放 —— 已结束的会话走同一条管线回放，包含打字动画，速度可选。
- 🔒 流模式 —— 服务端脱敏，失败即关闭；在 redact.json 里加你自己的规则。
- 🎛️ 控制（需主动开启） —— 在白名单文件夹里启动一个归你所有的 dsh 会话，发送消息，批准或拒绝命令，停止一轮对话，在轮次之间切换模型，查看模型/服务商和权限预设。只读会话保持只读。

完整布局：编辑器、控制台、聊天和活动栏。

日志视图：完整的智能体轨迹。

流模式：密钥和身份信息在服务端脱敏。

加载中：骨架行和带进度的历史条。

认识 Tail

Tail 就是 logo 里那个提示符箭头，开口处有一只眼睛。会话进行时它待在编辑器角落，陪着你：

- 它在看。 眼睛跟着你的指针转；没人理它时，它会瞟一眼智能体正忙的事，思考时则抬头看它的想法。
- 它会做出反应。 命令执行成功时，它跳一下并显示 ✓；失败时，它抖一抖并冒出一滴汗；一轮结束时撒彩带；你发消息时冒出一个小 !。会话闲置一分半钟，它打瞌睡；你靠近，它醒来。
- 它会出声思考。 模型思考时，三个点升进思考气泡，气泡里有一个时钟、最新一行推理和一些胡话（catching kittens、what is 42、negotiating with the compiler）。五分钟没有输出，它就在 STALLED? 警告下睡着。
- 它会玩。 长时间思考时它会无聊，自己玩十款游戏中的一款：贪吃蛇、俄罗斯方块、跑酷、国际象棋（回放名局）、chomp、太空侵略者、带飞船关卡的 geometry-dash、打砖块、flappy，还有打字游戏（敲 shell 命令）。▶ play 把操作权交给你（方向键和空格；Esc 交还，N 换下一款游戏），每款游戏的最高分都会保留。
- 它喜欢被摸。 点它。别太快，不然它会晕。

在监视墙上，每个智能体都有自己的 Tail，各用一种颜色。在 Settings 里可以关掉 Tail。

主题

Matrix（默认）、amber、red（crimson 与 bone）、ice、dracula、neon（synthwave），还有浅色的 paper 主题，都在 Settings 里选。每个主题都会给编辑器、括号配对、控制台、Tail 及其游戏配色，并让成功、错误和强调色彼此区分。

同时监视多个智能体

Alt+W（或智能体总览里的 Watch live）把屏幕拆成多个窗格，每个在线智能体一个：

- 每个窗格都是一个小 agenttail：编辑器随编辑发生逐字敲入，控制台显示命令、输出和退出状态，记分板显示编辑数、命令数、失败数、连续成功和 TOK/S，还有上下文计量条。
- Tail 出现在每个窗格。 每个智能体都有自己的 Tail，对它的命令和轮次做出反应；它思考时，思考气泡打开并显示时钟，长时间思考时还会开一局游戏，你可以用 ▶ play 接手（Esc 结束游戏，再按一次 Esc 关闭监视墙）。
- 舞台跟着智能体走。 命令运行时控制台升起，之后让位给编辑器；推理和回复以字幕形式滚动。每个窗格下方的 dock 用来切换或固定视图，💬 打开对话：你的消息和智能体的回复。
- 等待状态可见。 还没有输出的步骤会显示 waiting on the model，旁边带一个走动的时钟；超过五分钟则显示 stalled?。安静的智能体收缩成窄栏，把空间让给正在工作的智能体；但 需要你 的智能体例外：它的面板会加上琥珀色边框和 NEEDS YOU 标签，而且无论沉默多久都不收缩。
- 团队共用一棵文件树。 左栏按仓库列出智能体碰过的每个文件，带编辑次数，每个智能体一个圆点，各智能体当前打开的文件用其颜色标出。两个智能体同时改同一个文件会闪烁提示冲突。点击文件，就在该智能体的编辑器里打开它。
- 下方是时间线，按智能体铺开每个动作。
- 布局：FOCUS（每个面板一个舞台）或 SPLIT（编辑器和控制台上下叠放）；回复以字幕形式呈现，可放在侧栏或控制台内。

实时状态、跟随模式与布局细节

实时状态由日志推导，绝不只看 mtime。服务器轮询文件大小和最后一个事件的时间戳；文件大小增长也算活动。

- ● live（绿色，脉动）—— 有未结束的轮次或步骤。只有后台任务不会让会话变成 live。
- ◐ idle（琥珀色）—— 最后一个轮次/步骤在 10 分钟内结束，或 仍有分离的后台任务在跑。后台这种情况显示 IDLE · BG，tooltip 和任务栏会写出任务名。
- ○ finished —— 其余情况。

降级需要连续两次轮询结果一致；升级立即生效。圆点的 tooltip 会说明 step 1 running, last event …、background job pwsh-…, 12 min 或 idle since …。选择器和状态流用同一套状态。

跟随模式默认开启：编辑器打开正在编辑的文件（空闲时打开最后编辑的文件），控制台自动滚动，聊天停在最新事件。手动点击会暂停跟随 30 秒，并显示 FOLLOW PAUSED；只要会话有编辑，编辑器就不会显示「SELECT A FILE TO INSPECT」。活动面板带绿色光晕和 ● active 标签。

布局： 控制台/聊天按约 55/45 停靠（控制台默认），高度占窗口 28%；聊天至少保留 420 px。拖动水平分隔条调整底部高度（双击恢复/最小化），拖动垂直分隔条调整比例。文件树可折叠成 28 px 的窄条，带碰过文件数的徽标；聊天栏显示未读数和一个思考指示器。尺寸和折叠状态保存在 localStorage。窗口窄于 1000 px 时，新配置档默认折叠文件树和聊天。

可读性： 标题文字至少 13 px，大写标签 11 px，数值 14–15 px，面板标题 11 px，CPU/RAM/GPU 条宽 48 px。UI 缩放为 90/100/115/130%；新配置档在宽屏（>1600 px）下默认 115%。
后台任务会显示一条运行条，由 job/registered/job/settled 驱动，断线重连后依然保留。重定向的日志在任务运行期间会被跟踪读取（先读最后 2 KiB，再读新增行）；UTF-16LE 编码的 PowerShell 输出会被解码。没有重定向的任务仍会显示起始行、运行条和最终结果。

回放对已结束的会话开启：它会重置编辑器/树/控制台，让整个事件流重新走同一条管线，包括打字过程，节奏由速度滑块控制。实时会话无法回放。

聊天、系统仪表和视觉效果

智能体聊天是右侧停靠面板：智能体消息全对比度显示，围栏代码以等宽块呈现，还有用户轮次、思考行和分组的工具调用。Chat 把工具调用/思考分组，方便阅读；Log 是完整轨迹。系统注入默认隐藏；面板有固定开关，最小宽度保持 420 px。空条从不渲染。

系统仪表显示 CPU、RAM 和 GPU，旁边是步数、token、吞吐量和预估成本。CPU/RAM 每 2 s 从 os.cpus() 的差值采样；GPU 使用一个长期存活的 nvidia-smi 进程，在第一个 SSE 客户端接入时启动，在最后一个客户端断开或 dispose 时停止。没有 nvidia-smi 时，GPU 仪表显示 n/a，其余功能照常工作。

视觉效果在 Settings 里（页头的齿轮）：回放速度、效果强度、启动序列、matrix rain、spark line、光标、glitch、heat、跟随模式、显示系统和显示隐藏文件。

需要你

智能体在等待权限、回答或决定时不会写任何东西，所以很容易被忽略。agenttail 给每个来源一个状态：

- NEEDS YOU（琥珀色）：智能体无法继续，直到你采取行动。
- READY（绿色）：轮次已结束，智能体等待下一个提示词。
- 其他情况就是通常的实时、空闲或已结束状态。

每个信号都会说明它是怎么被看到的（acp、状态文件、日志、转录），以及有多确定；桌面通知只对 sure 和 probable 触发。

| 来源 | 信号 | 确定？ |
| dsh | 会话日志里有 approval/asked，却没有匹配的 approval/decided，同时会话看起来仍在运行。unavailable 的决定（没人可问）和超过 30 分钟的询问（崩溃）不算。 | sure |
| dsh，服务商故障 | 日志里最新的未解决故障是额度用尽（HTTP 402、余额不足、配额）或凭据缺失。之后成功的回复或新轮次会清除它，超过 6 小时的故障不再提示。速率限制、超时和服务器错误显示为红色标记，但不需要人处理。 | sure |
| Claude Code | 进程存活期间，~/.claude/sessions/<pid>.json 中出现 status: waiting：权限提示、等待输入、沙箱请求、worker 请求或打开的对话框。没有该状态时，则看 transcript 中是否有未应答的 AskUserQuestion 或 ExitPlanMode。其他任何未完成的工具调用都不说明问题：无论你正在决策，还是命令执行缓慢，看起来都一样。 | 确定（状态文件），可能（transcript） |
| Antigravity CLI | CLI 自己的日志中出现 Surfacing tool confirmation 行，其后没有对应的 Tool confirmation for conversation ... step N，且写入该日志的进程仍存活（pid 和启动时间，与 Claude Code 相同），并且该步骤尚未出现在 transcript 中。仅凭 transcript 永远看不出等待：等待中的步骤只有在运行后才会写入。Antigravity 编辑器不写这种日志，因此它的提示不可见，agenttail 会明确说明这一点。 | 可能（无法读取进程启动时间时靠推测） |
| 由 agenttail 托管（--allow-control） | 待处理的 ACP 权限请求，可精确得知 | 确定 |

一个会话无论被多少个信号看到，都只计一次（托管会话既出现在日志中，也通过 ACP 出现）。显示位置：会话选择器（需要你处理的会话排在最前）、智能体总览、监视墙、标签页标题（(2) ⚠ agenttail）和 favicon、可选的桌面通知（在设置中开启，仅在标签页处于后台时发送），以及活动栏中的收件箱按钮（Alt+I），它列出所有需要你处理的事项，并带有 Open session；对于托管会话，还就地提供 Approve 和 Reject。有事情开始需要你处理时，Tail 会提醒你。在流模式下，上述所有位置都只显示等待类型和工具名，绝不显示命令或路径，收件箱也没有 Approve 或 Reject 按钮（控制已锁定）。

权限模式

徽章表示智能体在未经你许可的情况下可以做到什么程度。它在工具提示中显示 harness 自己的模式名，并把该模式归入几个层级之一，因此 bypassPermissions、always-proceed 和 danger-full-access + never 都显示为 BYPASS。层级始终以文字表示，绝不只用颜色。表中没有的模式名按 harness 写入的原样显示，使用中性徽章，绝不猜测。设置跨越多个层级的会话，取风险最高的那一层。

| 层级 | DeepSeek Harness | Claude Code | Antigravity CLI | Antigravity 编辑器 |
| ASKS | workspace-write + 审批 ask | default、manual | toolPermission request-review、strict | 预设 REQUEST_REVIEW；自动执行 OFF；非工作区访问 ASK 或 DENY |
| EDITS（自行编辑） | | acceptEdits | proceed-in-sandbox；--mode accept-edits | 预设 AUTO；自动执行 AUTO |
| REVIEWER（由审查者决定） | auto 审查集成，带完全访问标志 | auto | --mode auto | |
| PLAN | 预设 plan | plan | --mode plan | |
| REFUSES（拒绝而非询问） | | dontAsk | | |
| BYPASS | danger-full-access + 审批 never | bypassPermissions | always-proceed、--dangerously-skip-permissions | 预设 TURBO；自动执行 EAGER；非工作区访问 ALLOW |

每个徽章还会标明读数的新旧程度，因为数据来源各不相同：

- DeepSeek Harness：精确。 日志记录预设、沙箱和审批策略，包括会话中途的切换。会话运行期间从 workspace-write 切到 danger-full-access + never，会在聊天、Log 视图和控制台各加一行告警。以 bypass 启动的会话没有发生切换，因此没有告警。每个子代理会话都有自己的日志，各自保留自己的读数。
- Claude Code：截至最近一次提示词。 permissionMode 写在你的提示词上，所以切换（Shift+Tab）从下一条提示词开始显示。没有模式的记录不带徽章。
- Antigravity 命令行：截至进程启动。 命令行的日志只在进程启动时记录一次 toolPermission 设置，agenttail 只读这个值（启动行里点名了 --mode 值或 --dangerously-skip-permissions 时，也一并读取）。你在会话内循环切换到的模式不会被记录，所以徽章注明这是进程启动时的读数。只有进程日志仍在磁盘上的对话才有徽章。
- Antigravity 编辑器：配置值。 编辑器的设置文件（~/.gemini/config/config.json，只读，只读 userSettings 里的 permissionPreset、autoExecutionPolicy 和 nonWorkspaceFileAccessPolicy 三个键）说明的是配置了什么，不是某次对话做了什么，所以提示框写的是「configured as」。

流模式下，原始模式名和其他内容一样，走同一套脱敏处理。

流模式

[!WARNING]
脱敏降低风险，但不保证安全。分享、推流或录制之前，先检查流内容。

流模式默认开启。脱敏在服务端完成，之后才会发送到浏览器，或由文件 API 写入。

- 密钥：服务商 API 密钥、GitHub token、AWS 密钥、bearer token、JWT、私钥块、URL 凭据，以及 token/密码查询参数。
- 身份：邮箱、用户路径里的 Windows 用户名、计算机/用户环境变量值、SID。
- 环境输出：env/printenv/set 转储保留变量名，丢掉变量值。
- 网络：IPv4/IPv6 地址（包括 URL 里的 IP，端口保留）、MAC 地址、PlayStation 风格主机名和 SSID: 值。
- 不透明标识符：UUID、call/tool/message/request id，以及日志文本里的 pwsh-… 作业 id。
- 私有根路径和发布名：配置的路径和 scene 风格发布压缩包。
- 其余内容默认全部脱敏：每个事件、每个响应的每个文本字段都会脱敏，只有 id 和页面匹配的少数协议词例外。这样以后新增的字段也绝不会原样显示。会话列表、智能体总览、实时头部、文件与目录树响应、错误消息，都走同一个脱敏器。

替换尽量保持长度不变（用 ▓）。脱敏过程抛错时，事件会被丢弃（fail closed），绝不会原样发出。在 redact.json 里添加字面量或正则，分享任何内容前先验证结果。

控制（需主动开启）

控制默认关闭。加上 --allow-control 启动，agenttail 才能通过 dsh --profile acp 启动并接管 DeepSeek Harness 会话：

npx github:ionut27001/agenttail --allow-control --no-stream-mode

服务端会打印一个 URL，fragment 里带随机 32 字节 token：

http://127.0.0.1:8787/#token=…

每个控制类 POST 除了原有的 Host、Origin、Content-Type 检查，还要带 Authorization: Bearer <token>。URL 要保密；能读到它的人就能操控 agenttail 接管的会话。每次启动都会重新生成 token。

流模式会锁死控制。 流模式默认开启，所以只加 --allow-control 会看到「control disabled in stream mode」提示，控制请求一律返回 403。只有确实需要往智能体里输入时，才用 --no-stream-mode。

控制能做什么

- 新建会话 —— 选一个白名单内的工作区、一个权限预设（默认 workspace-write，也可选 read-only，或经明确确认后选 danger-full-access）、一个来自实时 dsh 目录的模型（包括 ACP 配置档里配好的 Ollama 等自定义服务商），再填第一条消息。
- 输入 —— Enter 发送；Shift+Enter 换行。回合进行中发出的消息会排队，等该回合结束后再发。输入框旁的模型选择器为下一回合切换模型（取自实时 dsh 目录）。粘贴的图片只在智能体声明支持图片提示词时才发送；dsh 的 ACP 不支持，所以 agenttail 会直接说明，而不是把图片发出去。

- Approvals — the exact command, file paths and diff appear first, the agent's own title last, with Approve and Reject. Approve always means "allow once": agenttail never picks an agent's "always allow" option, and refuses to approve a request that came with no command or file details, or a card that changed after you saw it (it shows what changed). Reject accepts an optional short reason. The inbox (Alt+I) lists the pending approvals of every owned session with Approve and Reject in place. agenttail never auto-approves.
- Stop — cancels the running turn and kills the tool process. End closes the owned session; it becomes view-only.
- Owned vs view-only — sessions started by agenttail are marked ◈. Sessions started by the Desktop app or another process are view-only: dsh does not expose a live attach surface, and a second process cannot resume an active session (session … is already owned by an active write handle).

Sessions started by agenttail are ordinary dsh sessions under ~/.dsh/sessions; after agenttail stops they remain visible as view-only sessions. The dsh log is still the read side's source of truth: model/provider, permission preset, approval-policy changes, per-turn tokens and cost, and background jobs come from the log.

Risks in plain words: control starts a coding agent that can run commands and edit files in the chosen workspace. The permission preset is enforced by dsh, not by agenttail. workspace-write is the default, but it is still a write-capable agent; review approvals. danger-full-access removes the sandbox and is available only through an explicit confirmation. Prefer a scratch folder and a narrow control.json allowlist.

Security and privacy

- Read-only by default. Without --allow-control the server only reads session logs, transcripts, workspace files and, for needs you, the status fields of Claude Code's ~/.claude/sessions/<pid>.json files; its only writes are local nicknames and optional config files in the per-user config directory. Control is opt-in and starts its own dsh sessions; the Desktop app's sessions are never attached to.
- Localhost only. The server binds to 127.0.0.1; there is no remote listener. Read-only endpoints have no authentication; control endpoints require the per-start token.
- DNS rebinding blocked. Every request must carry Host: 127.0.0.1:<port> or Host: localhost:<port>, otherwise 403.
- CSRF blocked. POST requests require an Origin matching the exact Host and Content-Type: application/json, otherwise 403 before the body is read. Control POSTs additionally require Authorization: Bearer <token>.
- Control locked in stream mode. With stream mode on (the default), the input box and approval buttons are hidden and control requests return 403.
- No auto-approve. Every approval is a human click; the dsh permission preset is the enforcement boundary.
- Claude Code status files. Only the numbered ~/.claude/sessions/<pid>.json files are opened, and only the pid, session id, status, what it waits for and when are kept. The sibling .key files are never opened. A status counts only while its process is alive (a signal-0 check, nothing is sent to it) and fresh. AGENTTAIL_CLAUDE_SESSIONS_DIR changes the folder.
- No telemetry. agenttail collects no analytics, crash reports or usage data.
- No external requests from agenttail. Monaco, xterm.js and JetBrains Mono are vendored under public/vendor/ with their licenses. The page loads no CDN and works offline. A controlled dsh session may call its configured model provider, just like a normal dsh session.

See SECURITY.md for vulnerability reporting and the full privacy statement.

Configuration and environment variables

Configuration lives in a per-user directory, never in the repo:

| Platform | Config directory |
| Windows | %APPDATA%\agenttail\ |
| macOS / Linux | ~/.config/agenttail/ (or $XDG_CONFIG_HOME/agenttail/) |

Files: roots.json, redact.json, nicknames.json and (when control is used) control.json plus control-audit.log. Copy roots.example.json, redact.example.json and control.example.json there to start.

roots.json is the read-only allowlist for extra workspaces and the tree ignore list:

{
"roots": [{ "path": "/path/to/another-project", "as": "example" }],
"privateRoots": [],
"ignore": [".git", ".tmp", "node_modules", "build", "build-", "_"]
}

The session workspace is always allowed. Junctions/symlinks are followed only when their real target is an allowed root; otherwise they are listed but not expanded. as maps an allowed root back into the workspace tree, and .., unrelated absolute paths, UNC paths and symlink escapes get 403. Tree nodes carry an opaque key so redacted display names still open files. Paths the session touched are injected even when the breadth-first walk hits its node/depth budget. ignore supports exact names and suffix prefix matching; show hidden files in the ⋯ menu re-fetches the tree.

control.json is the write-capable workspace allowlist for sessions agenttail starts. Only paths listed here can be chosen in the New Session dialog:

{
"workspaces": [
"E:\\dev\\scratch"
],
"dshProfile": "acp",
"dshHome": "C:\\Users\\you\\.dsh",
"maxSessions": 8
}

dshProfile defaults to acp; dshHome and patch are optional. A custom provider such as Ollama must be configured in that ACP profile (or passed as a patch overlay) before it appears in the model picker. workspaces is the only required field.

The same file can describe several harnesses in a harnesses block instead of the dsh… keys (which keep working and are read as harnesses.dsh when the block is absent):

{
"workspaces": ["E:\\dev\\scratch"],
"defaultHarness": "dsh",
"harnesses": {
"dsh": { "label": "DeepSeek Harness", "profile": "acp" }
}
}

Each entry takes label, kind (dsh or acp), command and args (absolute paths recommended), envPass (names of environment variables to pass through), env (fixed values), presets ({ id, label, danger?, env | mode | config }), defaultPreset and log (which adapter shows its sessions). Commands come only from this file, never from the page or an API request, and agenttail never downloads or installs a harness. A harness other than dsh gets only the basic environment (path, system, temp and home variables) plus envPass; environment values never reach the page or the audit log. A danger preset, or switching a running session to its mode, needs the explicit confirmation. The New Session dialog shows a harness picker only when there is more than one, with the command line that will run. In this release only harnesses shown by the dsh log adapter can be started; driving Claude Code, Antigravity and other harnesses is the next release (see docs/dev/hub-roadmap.md).

| Variable | Default | Purpose |
| PORT | 8787 | HTTP port, bound to 127.0.0.1 |
| AGENTTAIL_CONFIG_DIR | per-user dir above | Configuration location |
| AGENTTAIL_ROOTS_FILE | <config>/roots.json | Allowlisted roots and ignore list |
| AGENTTAIL_REDACT_FILE | <config>/redact.json | Extra redaction literals/patterns |
| AGENTTAIL_NICKNAMES_FILE | <config>/nicknames.json | Local display nicknames |
| AGENTTAIL_CONTROL_FILE | <config>/control.json | Workspace allowlist for owned sessions |
| AGENTTAIL_CONTROL_AUDIT_FILE | <config>/control-audit.log | Control audit log (timestamp, action, session id; no message bodies) |
| AGENTTAIL_POLL_MS | 700 | Log poll interval |
| AGENTTAIL_STREAM_MODE | on | Set off to disable redaction (not recommended) |
| DSH_SESSIONS_ROOT | ~/.dsh/sessions | DeepSeek Harness session root |
| CLAUDE_PROJECTS_ROOT | ~/.claude/projects | Claude Code transcripts |
| AGENTTAIL_CLAUDE_SESSIONS_DIR | ~/.claude/sessions | Claude Code status files (status fields only) |
| ANTIGRAVITY_ROOT | ~/.gemini/antigravity/brain and ~/.gemini/antigravity-cli/brain | One Antigravity brain folder to read instead of both |
| ANTIGRAVITY_CLI_DIR | ~/.gemini/antigravity-cli (the parent of ANTIGRAVITY_ROOT when that is set) | Antigravity CLI folder whose log/ is read for needs-you and for the permission mode |
| ANTIGRAVITY_CONFIG_FILE | config/config.json beside the CLI folder (~/.gemini/config/config.json) | The Antigravity editor's settings file, read for the permission mode of editor conversations |
| AGENTTAIL_NO_OPEN | unset | Set 1 to skip opening the browser |

--allow-control, --no-open and --no-stream-mode are accepted on the command line.

Keyboard shortcuts

| Shortcut | Action |
| Ctrl+B | collapse/expand the workspace tree |
| Ctrl+J | collapse/expand the bottom area |
| Ctrl+. | collapse/expand the agent chat |
| Ctrl+Shift+. | dock the agent pane to the right side (full height) or back under the editor |
| Alt+A | open the agents overview |
| Alt+W | watch the live agents side by side, one pane each |
| Alt+I | open the inbox: everything that needs you |
| ? | list every keyboard shortcut |

How it works

flowchart LR
A[DeepSeek Harness logs] --> D[Adapters]
B[Claude Code transcripts] --> D
C[Antigravity transcripts] --> D
D --> E[Normalized events]
E --> F[Stream mode redaction]
F --> G[SSE]
G --> H[Dashboard UI]

Each source adapter tail-decodes its log and maps it to a common event shape (say, call, result, job, jobOutput, thinking, user, step). The server watches file size and the last event timestamp, derives the live state from open turns/steps/jobs, and streams history first and then live events over one SSE connection. The page renders that stream into the tree, editor, console, chat and activity bar. There is no database and no browser build step.

Development and limits

npm test # smoke, roots, redaction, sources, control and headless Edge UI suites
node scripts/demo-session.mjs --play # synthetic demo (no real data)
node scripts/capture.mjs # regenerate docs assets

The test suites use temporary synthetic fixtures only. The UI suite drives Edge through the DevTools protocol; set EDGE_PATH if Edge is not in its default location. Dev-only tools (esbuild, postject, gifenc, pngjs) are used for the release build and asset capture; the runtime has no dependencies.

The control design and the dsh ACP evidence are recorded in docs/dev/input-design.md.

- smoke — dsh API/SSE, live/idle/finished states, stale-mtime growth, hysteresis, system user classification, nicknames, job output, sorting, source counts, sys samples, Host/Origin/Content-Type checks.
- roots — allowlisted roots, junction follow/deny, opaque keys, traversal, touched deep paths, ignore list/show-hidden.
- redact — every redaction category, IP:port/UUID/opaque-id rules, network boundaries, live redact.json, fail-closed and off mode, and a Claude Code and an Antigravity fixture whose every text field carries a token, a user name in a home path, an email and an IP, checked across every endpoint the page reads.
- sources — Claude custom titles/subagents/thinking/pending live, replies counted once, turns and API-equivalent prices, Antigravity normalization, tokens, deletes and live tail, and the permission mode of Claude Code, Antigravity CLI and dsh sessions (a bypass switch mid-run raises an alert).
- control — opt-in gate (404), token (401), stream-mode lockout (403), foreign Origin (403), ACP start/message/approve/stop/close, queueing, audit-without-bodies.
- agents — the agents overview API, repository and worktree grouping, colours, /app/ asset security, stream tail and lite mode.
- attention — the needs-you model and merge, dsh open asks (closed, unavailable, crashed), Claude Code status files (busy, each waiting reason, dead pid, unknown shape, a .key file left unread) and transcript rules, the Antigravity CLI log (open, answered, denied, a new message, an exited or reused process, a stale log, New Year), an owned session counted once, the inbox endpoint, and the permission tier tables, the CLI log's toolPermission and flags, the editor settings file and a dsh log that switches into bypass.
- ui — headless Edge: header, compact picker, meters, activity states, follow, tree legend/tooltips/show-hidden, skeleton/loading bar, chat Chat|Log and grouped tools, replay, splitter persistence, themes, the console stage, Tail and its ten games, the watch wall (panes, focus stage, chat modes, team tree, timeline, quiet agents, a Tail per pane), needs-you (header, tab title and favicon count, notification, picker, overview, wall, inbox, no command text), the permission badge (picker, header, overview, wall, loud BYPASS, no personal data), vendored assets, reduced motion and 900/720 px layouts.

Build a standalone Windows exe and the package/portable archives with node scripts/build-sea.mjs. Artifacts go to dist/ (git-ignored).

Limits

- Only the newest sessions per source are listed (60 dsh/Claude, 40 Antigravity).
- Antigravity writes a command that is still running once and does not rewrite it when it ends, so agenttail can only show it as running with its partial output; the final output and exit code are not in the transcript.
- Control starts one dsh --profile acp process per owned session, because the permission preset is process-level in dsh. ACP is automation-only: no plans, commands, terminals or client filesystem operations.
- Sessions started outside agenttail are view-only; dsh rejects a second controller for an active session.
- The permission mode of the Antigravity CLI comes from its log, which is not a documented interface: the toolPermission line is read as it has been seen, and a --mode or --dangerously-skip-permissions flag only counts when a startup line names it. The editor's settings file is shared and describes what is configured, not what one conversation did. DeepSeek Harness plan mode has not been seen in a log yet, so only a preset named plan is read as plan.
- Needs-you for Claude Code relies on a status file Claude Code writes for itself; its layout is not a documented contract, so an unexpected shape means no signal and the transcript rules take over. A permission prompt is invisible in the transcript alone. Needs-you for the Antigravity CLI reads its log, which is not a documented interface either; it has been seen closing a prompt in print mode, so it stays probable until an interactive approval has been checked. The Antigravity editor has no signal. Browser notifications work only while the agenttail tab is open.
- The tree is a snapshot (2,500 nodes, 12 levels); files created later appear when touched if their parent is known.
- Peak/off-peak pricing ignores public holidays, and the DeepSeek cost is a list-price estimate, not a bill (the pro peak rate is taken as the flash 2x band); the Claude API-equivalent cost uses list prices (no batch, regional or long-context surcharges) and skips models without a list price; GPU metering needs nvidia-smi.
- Windows is tested. macOS and Linux are untested. The Windows exe is unsigned, so SmartScreen may warn.
- .dsh logs are decoded as zstd frames; corrupted frames are skipped.

License

MIT © 2026 ionut27001. See LICENSE.

agenttail is not affiliated with DeepSeek, Anthropic or Google. Product names are used only to describe supported sources.