agenttodo-hud

本地优先。 任务只保存在本机 SQLite，网关只监听 127.0.0.1；没有账号、云端同步与遥测。

为什么

待办应用不缺，缺的是把「整理」交出去、把「专注」留下来的那一个。

AgentTodo HUD 常驻桌面一角，通过 MCP / HTTP 与你的 Agent 协作：你随口说一句，它把时间、优先级与步骤都排好；你只需要看下一件事，然后完成它。它不内置大模型，也不依赖任何云服务。

Related MCP server: tasqr-mcp

亮点

• 一句话录入 —— 记一下：明天下午3点前交测试包，P1，30分钟 #发布，截止时间、优先级、时长、标签与子步骤全部在本地解析。

• Agent 接入 —— MCP Streamable HTTP / stdio、HTTP API、SSE；复制一段提示词，Agent 自己完成注册与自检。

• 桌面 HUD —— 无边框透明窗口，始终置顶、鼠标穿透、托盘驻留；实时捕获并模糊 HUD 背后的桌面，做出 iOS 式毛玻璃（约每 8 秒刷新）。

• 日与夜，自动切换 —— 06:00–18:00 日间霜面玻璃，其余时间夜间极光玻璃；跨过边界时平滑过渡。

• 键盘优先 —— Ctrl / ⌘ + K 命令面板、N 新建、/ 搜索、? 快捷键、1–5 切页；完成与归档都可以撤销。

• 本地优先 —— SQLite + WAL，凭据只存哈希，网关拒绝跨域写入；没有后台云服务，不需要注册。

桌面 HUD

卡片内是实时捕获并模糊的桌面，卡片外保持清晰；毛玻璃约每 8 秒刷新一次，显示、拖动结束与鼠标进入时会立即刷新。Alt + Space 切换穿透，Alt + H 显示 / 隐藏，Alt + Enter 完成当前第一项。

快速开始

环境：Windows 11（Windows 10 理论兼容，未单独验证）· Node.js ≥ 22.13 · npm

npm install
npm run dev

npm run dev 会同时启动本地网关（127.0.0.1:17530）、Vite（127.0.0.1:5173，HMR）与 Electron 桌面端。关闭窗口只会收进托盘，结束开发请按 Ctrl + C。

仓库暂不提供预编译安装包；npm run package 可生成 Windows 便携版。首次启动是空列表，可点「载入文档示例」快速预览完整界面。

Windows 上也可以直接双击 启动 AgentTodo.cmd：自动安装依赖、构建并打开应用。手动运行构建产物：

npm run build
npm start

常用命令

接入 Agent

推荐「提示词接入」，不需要手写配置：

1. 打开应用 → Agent 接入 → 复制接入提示词；

2. 粘贴给能在本机执行命令或发送 HTTP 请求的 Agent；

3. Agent 自动注册、保存凭据，并读取现有待办完成自检；接入列表实时更新。

提示词 30 分钟内有效；已接入的 Agent 使用自己的持久凭据继续工作，凭据只保存哈希。

MCP 客户端也可以直接连接（需先启动应用，保持本地网关运行）：

{
  "mcpServers": {
    "agenttodo-hud": { "url": "http://127.0.0.1:17530/mcp" }
  }
}

工具：quick_capture · get_active_tasks · sync_todo_list · update_task_status · append_subtasks · connect_agent

stdio 客户端用 server/stdio.mjs（或 npm run mcp）启动桥接，只访问本地网关，不会另开数据库。

一句话录入

记一下：明天下午3点前把周报发给老王，P1，30分钟 #工作；顺便清理已合并的本地分支

Agent 调用 quick_capture（HTTP 为 POST /api/v1/tasks/capture），服务端在本地一步解析并写入：

重复说同一件事不会重复建卡，只补全缺失的时间、时长与标签；支持 dry_run 预览，同一次录入可在同步条整体撤销。解析器不依赖大模型，离线可用。

服务只监听 127.0.0.1:17530，拒绝非本机 Host 与未知网页 Origin。下列为常用端点，完整参数与同步模式见 完整使用手册。

同步支持 merge_and_reprioritize、append_only、replace_all_pending 三种模式；所有写入在事务内完成，revision 单调递增。

技术栈

项目结构

src/       React 界面：任务总览、专注、已完成、Agent 接入、设置、桌面 HUD
desktop/   Electron 主进程、托盘与窗口管理、HUD 毛玻璃捕获、受限 preload
server/    SQLite 领域层、本地自然语言解析、Express 网关、MCP HTTP / stdio
tests/     59 个后端 / 网关 / MCP / 持久化 / 解析用例
scripts/   构建、打包、产物验证、Playwright 冒烟 / 视觉 / 主题脚本
docs/      完整手册、优化记录、特性实现与验收报告
design/    设计规范与概念图
public/    首帧主题引导脚本与 favicon

文档

更多界面

数据与隐私

• 桌面端数据库：%APPDATA%/AgentTodo HUD/tasks.sqlite；开发网关：.data/tasks.sqlite

• 网关只监听本机，拒绝非本机 Host 与未知 Origin；不提供云端中转

• Agent 凭据只保存哈希，导出与公共状态不包含私钥

• 没有账号、遥测与云端依赖；关闭桌面应用后，由它启动的本地网关也会停止

• 删除 %APPDATA%/AgentTodo HUD 目录即可清空全部数据

已知边界

• Windows 11 上完成 v0.5.0 验收；Windows 10 理论兼容但未单独验证；macOS 源码路径兼容，未实测

• 毛玻璃约每 8 秒刷新；每次刷新约 0.3 秒的捕获窗口内，HUD 不会出现在其他程序的截图 / 录屏里，其余时间正常可见

• 远程云端或网页版 Agent 无法直接访问 127.0.0.1，需要在本机运行桥接

• 图标层嵌入、全屏检测自动折叠、开机自启、远程中转与内置大模型尚未实现

License

MIT © 2026 AgentTodo HUD