quadtodo

v0.1.1

Published

12 days ago

Local four-quadrant todo CLI with embedded Claude Code / Codex terminal

0High
0Medium
0Low

lzh2799216683

cli todo quadrant claude-code codex terminal

quadtodo

本地四象限待办 CLI，每条 todo 可内嵌一个 Claude Code 或 Codex 终端会话。单 Node 进程自包含，不依赖云服务。

GitHub 仓库：[email protected]:LIUZHENHUA521/quadtodo.git

30 秒上手

npm install -g quadtodo            # 装 quadtodo 本体
quadtodo install-tools --all       # 装 claude + codex（AI 终端必需）
quadtodo doctor                    # 自检
quadtodo start                     # 自动打开浏览器 → http://127.0.0.1:5677

平台：仅支持 macOS / Linux；Windows 暂不支持，规划中。

依赖

Node 20+
npm 10+
claude / codex（AI 终端必需）—— 没装的话跑 quadtodo install-tools --all，或手动 npm i -g @anthropic-ai/claude-code @openai/codex
macOS / Linux（Windows 暂不支持）

安装

从 npm 全局安装

npm install -g quadtodo

首次安装后，建议先执行：

quadtodo doctor

从源码安装

cd quadtodo
npm install                 # 后端依赖 + node-pty 原生编译
cd web && npm install       # 前端依赖
cd ..
npm run build               # 前端构建，产物在 dist-web/
cd ..
npm link                    # 全局链接 `quadtodo` 命令

快速开始

quadtodo doctor             # 检查环境是否就绪
quadtodo start              # 启动服务并自动打开浏览器
# → http://127.0.0.1:5677

停止：在前台会话按 Ctrl+C，或在另一个终端里 quadtodo stop。

给 Claude Code 当知识库用（MCP）

quadtodo 内置了一个 MCP Streamable HTTP 服务（POST /mcp），17 个工具覆盖搜索 / 增删改 / 合并 / 归档 / 批量操作 / AI 会话日志检索。外部 Claude Code session 配上之后，可以用自然语言"帮我清理重复的 todo"、"最近一周我在忙啥"、"合并这三条关于登录的 todo"。

一键接入：

quadtodo mcp install   # 把 quadtodo 写进 ~/.claude/settings.json 的 mcpServers
quadtodo mcp status    # 健康检查

完整工具清单 + preview/confirm 安全模型 + ⌘K 面板说明：docs/MCP.md。

通过 Telegram supergroup 使用（每任务一个 Topic）⭐ 推荐

quadtodo 直接跑一个 Telegram bot，每开一个 task 自动建一个 Forum Topic，对话物理隔离；内容直接从 Claude Code jsonl 日志读（干净，无 spinner / ANSI 噪声）；任务结束 close topic + 改名 ✅。

详见 docs/TELEGRAM.md。

通过 OpenClaw 在微信里使用（双向）

把 quadtodo 接到 OpenClaw 的微信渠道，实现"在微信里跟 AI 助理说一句『帮我做：X』就自动建 todo + 启动 Claude Code，AI 卡到决策点又能在微信里推给你选"的工作流。

详见 docs/OPENCLAW.md —— 5 步启用清单 + P0 端到端验证表。

手机访问（Tailscale 私网）

想在外面用手机继续看待办 / 接 AI 会话？详见 docs/MOBILE.md —— 基于 Tailscale 私有 mesh VPN，不暴露公网，配置 5 分钟。

安全提醒：quadtodo 内置 shell + AI 终端能力，绝对不要直接暴露到公网。Tailscale 私网是推荐的访问方式。

快速上手：

# 一次性把监听地址改成 0.0.0.0（否则 Tailscale 网卡也不可达）
quadtodo config set host 0.0.0.0
quadtodo start
# 或者：quadtodo start --expose

命令

| 命令 | 作用 | |---|---| | quadtodo start [--port 5677] [--host 0.0.0.0] [--expose] [--no-open] [--cwd <path>] | 启动服务（--expose = --host 0.0.0.0） | | quadtodo stop | 停止服务（SIGTERM 3 秒后 SIGKILL） | | quadtodo status | 查看运行状态 + 活跃会话数 | | quadtodo doctor | 环境自检 | | quadtodo config get <key> | 读配置项 | | quadtodo config set <key> <value> | 写配置项 | | quadtodo config list | 打印整份配置 |

配置

配置文件：~/.quadtodo/config.json

{
  "port": 5677,
  "host": "127.0.0.1",
  "defaultTool": "claude",
  "defaultCwd": "~",
  "tools": {
    "claude": { "command": "claude", "bin": "claude", "args": [] },
    "codex":  { "command": "codex",  "bin": "codex",  "args": [] }
  }
}

示例：

quadtodo config set port 6000
quadtodo config set tools.claude.command claude-w
quadtodo config set tools.codex.command codex-w
quadtodo config set tools.claude.bin /usr/local/bin/claude
quadtodo config set tools.codex.bin /opt/homebrew/bin/codex

说明：

tools.<tool>.command：启动命令名，适合 claude-w / codex-w 这种公司内封装命令
tools.<tool>.bin：绝对路径覆盖，优先级高于 command

数据存储

~/.quadtodo/
├── config.json      # 配置
├── data.db          # SQLite: todos 表
├── quadtodo.pid     # 服务运行时的 PID
└── logs/            # 每个 AI 会话的完整日志（最后 512KB）
    └── ai-*.log

导出/迁移：整个 ~/.quadtodo/ 是一个普通目录，tar 打包即可。

统计与周/月报告

顶栏 📊 按钮打开"统计"抽屉：展示所选时段的 AI 活跃时长、墙钟时长、token 消耗、成本估算与 Top 10 任务，支持复制/下载 Markdown 周报。

单价默认内置，也可在 ~/.quadtodo/config.json 的 pricing 段里 override：

"pricing": {
  "models": {
    "claude-opus-4-*":   { "input": 15.00, "output": 75.00, "cacheRead": 1.50, "cacheWrite": 18.75 }
  },
  "cnyRate": 7.2
}

活跃时长的空闲阈值（默认 120s）可通过 stats.idleThresholdMs 调整。

迁移到另一台电脑

# 在源机器
git clone <this-repo-url> ~/code/quadtodo
cd ~/code/quadtodo/quadtodo
npm install
cd web && npm install && npm run build && cd ..
npm link

# 如果要带走现有 todo 数据：
scp -r ~/.quadtodo target-host:~/

从零开始的目录结构

quadtodo/
├── package.json      # 后端 deps: express / ws / node-pty / better-sqlite3
├── src/
│   ├── cli.js        # commander 入口
│   ├── config.js     # ~/.quadtodo/config.json 读写
│   ├── db.js         # better-sqlite3 包装
│   ├── pty.js        # PtyManager（node-pty 会话 Map）
│   ├── server.js     # Express + ws + 路由组装
│   └── routes/
│       ├── todos.js
│       └── ai-terminal.js
└── web/
    ├── package.json  # 前端独立：vite + react + antd + dnd-kit + xterm
    └── src/
        ├── main.tsx
        ├── TodoManage.tsx   # 四象限看板主页
        ├── TodoManage.css
        ├── AiTerminalMini.tsx
        ├── SettingsDrawer.tsx
        └── api.ts

故障排除

端口占用：quadtodo config set port <new>
claude 找不到：quadtodo config set tools.claude.bin /full/path/to/claude
node-pty 安装报错：通常是 node-gyp 找不到 C++ 工具链。macOS 装 Xcode Command Line Tools (xcode-select --install)
终端显示 session_not_found：会话已超时（30 分钟已结束的会话会被清理），重新点"启动 AI 终端"

todo 请完成以下待办任务:

标题: 后续工作描述: 一、提升 AI 协作效率（高价值）

会话对话增强
- 在待办详情里查看每个会话的完整历史（现在 log 落盘了但没 UI 查看），支持搜索 / 关键字高亮 - 一键从某个历史会话 fork 出新会话（基于已有上下文继续问不同方向）
- 会话间对比视图（同一任务用 Claude vs Codex 分别跑，并排看输出差异）
Prompt 模板库
- 把"脑爆模式"抽象成 prompt 预设系统：Bug 修复模板、重构模板、写测试模板、代码评审模板...
- 支持变量占位符（{{title}} / {{workDir}} / {{lastCommitDiff}}）
- 每个待办可选模板组合叠加
多会话编排
- 一个待办拆成多个子会话（规划 → 实现 → 测试 → review），可串行/并行触发
- 上一个会话的产出自动作为下一个的 prompt 前缀

二、状态感知 & 通知（中价值）

桌面通知 + 系统托盘
- pending_confirm 状态触发 macOS 原生通知 - 菜单栏图标显示"有 N 个待交互会话"徽标
静默工作时长统计
- 记录每个会话实际运行时长、token 消耗估算（解析 Claude 输出里的 usage）
- 每周/每月报告：我花最多时间的任务 Top10、AI 帮我完成了 X 小时工作
智能暂停检测
- 检测 AI 输出 N 分钟无变化 → 自动判定"卡住了"并通知
- 区分"在思考"和"真的卡了"（有 spinner / 没 spinner）

三、Git & 项目集成（高价值，crazyCombo 多仓库场景尤其适合）

Git 状态面板
- 每个待办关联 workDir，卡片上直接显示：当前分支、未提交文件数、落后/领先 origin 情况 - 一键"开始任务"：自动 checkout 新分支、命名来自 todo 标题
完成闭环
- AI 会话跑完后，自动 git diff --stat 展示到卡片上
- 一键生成 commit message（调 AI 基于 diff）
- 一键创建 PR（集成 gh CLI）
提交记录反向关联
- 扫描仓库最近 commit，自动匹配是哪个 todo 完成的（靠分支名/关键字）

四、任务管理体验（中低价值但体验好）

快捷键系统：n 新建、1-4 切象限、⌘K 命令面板、e 编辑
子任务 / Checklist：一个 todo 里可以有勾选列表
标签系统：# 标签筛选，颜色区分
重复任务：每日/每周自动生成（如"每日 standup"）
归档 & 回顾：done 超过 N 天自动归档到独立视图，避免列表臃肿
拖拽排序持久化 + 看板快照：每天结束自动存快照，能回看"昨天的看板长啥样"

五、数据与知识沉淀（长期价值）

全文检索
- 搜索词同时命中：todo 标题、描述、评论、AI 会话输出 - 这是相对独有的价值 —— 你的 AI 对话历史在本地，可被检索
"可复用经验"抽取
- 会话完成后，AI 自动生成一个摘要 + "下次遇到类似问题可复用的知识点"
- 沉淀到一个知识库 tab，下次新建相似 todo 时推荐相关经验
导出 / 分享
- 一个待办 + 其会话输出 → 导出为 Markdown（用于写周报、故障复盘）
- 飞书文档直推（你本身就有 lark skills）

请先理解需求和当前项目上下文，再开始执行。完成后请给出变更摘要、验证结果，以及仍需我确认的事项。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

quadtodo

30 秒上手

依赖

安装

从 npm 全局安装

从源码安装

快速开始

给 Claude Code 当知识库用（MCP）

通过 Telegram supergroup 使用（每任务一个 Topic）⭐ 推荐

通过 OpenClaw 在微信里使用（双向）

手机访问（Tailscale 私网）

命令

配置

数据存储

统计与周/月报告

迁移到另一台电脑

从零开始的目录结构

故障排除