Waypoint

Waypoint

Waypoint 会在你的 AI 编码工具之间维护一份项目日志，让你了解工作停在何处，以及接下来要做什么。

网站： waypoint.stifler.in

你会在不同项目以及 Claude Code、Codex 和 ChatGPT 之间切换。每个工具都有自己的记忆，但它们彼此都不知道对方做了什么。Waypoint 会为每个项目向所有工具提供同一份记录（项目是什么、上次停在何处、接下来要做什么、哪些事项需要关注），并显示这份记录落后于实际活动的情况。

故事设定： 每个项目都是一次航行，每个 AI 工具都是一名领航员，而日志簿是它们共同填写的航海日志。仪表板就是海图。

它处理两类事实：

• 事实（地点和时间）：哪个项目、哪个工具、何时发生、上次提交是什么。Waypoint 会从工具自己的本地历史记录和 git 中自动收集这些信息。
• 含义（做了什么以及为什么）：完成了什么、接下来要做什么、有什么阻碍。AI 工具会按照一条共享规则，将这些内容记录下来，写成简短的日志条目。

如果两者不一致，海图会如实显示。某个工具处理了项目却没有记录任何内容，就会留下一个未记录的值班时段（会话）。即使工具忘记遵守规则，海图也能保持准确。

$ waypoint refresh
Dashboard refreshed: 3 projects, 1 active this week, 1 attention item, 1 with unlogged sessions, 1 stale, 1 untracked folder.

这是虚构的日志簿，位于 examples/logbook/；其中的海图展示了每个案例。waypoint refresh 还会写入 chart.html，生成与海图相同的页面，供你在浏览器中打开。

开始使用

需要 Python 3.11 或更高版本；没有其他依赖项。方向键界面是可选的：安装 waypoint-mcp[tui]（会添加 Rich 和 prompt_toolkit），然后运行 waypoint。

macOS / Linux

pipx install waypoint-mcp         # or: python -m pip install waypoint-mcp
waypoint setup                    # fitting out: logbook, roots, the rule and MCP server for each AI CLI it finds
waypoint add ~/code/my-project    # chart a voyage (project); once per project
waypoint refresh                  # refresh the dashboard: DASHBOARD.md, dashboard.json and chart.html (--open opens it)
waypoint status                   # everything at a glance, with fixes for problems
waypoint archive <project>        # hide a finished project, keep its log (also: restore, remove, ignore)

Windows (PowerShell)

py -m pip install waypoint-mcp
waypoint setup
waypoint add $HOME\code\my-project
waypoint refresh

• 找不到 waypoint？ 其安装目录不在 PATH 中，AI 工具也需要将它加入 PATH（它们会启动 waypoint mcp）。如果使用 pipx 安装：运行 pipx ensurepath，然后打开新的终端。如果使用 pip 安装：将 pip 提示的 scripts 文件夹加入 PATH；在此之前，python -m waypoint …（Windows：py -m waypoint …）会使用同一个 Python 运行它。
• 界面（pipx install "waypoint-mcp[tui]"）：waypoint setup 会引导你配置日志簿、根目录、项目和 AI 工具，在 Review 中显示所有更改，并且在 Apply 前不会写入任何内容；之后单独运行 waypoint 即可管理项目（归档、恢复、移除、忽略、跟踪）和工具（连接、断开连接、修复漂移），并查看状态。按键：↑↓ 移动，Space 切换，Enter 下一步，← 返回，/ 搜索，Esc 退出。每项操作也都有对应的普通命令；不安装额外组件或使用任何 setup 标志时，会显示编号提示。支持 NO_COLOR。
• setup 会显示所有将要更改的文件，并一次性询问确认。它会记住日志簿，因此之后的命令无需使用 --logbook。它绝不会修改你自己的 CLAUDE.md 或 AGENTS.md 文本：它会添加 Waypoint 自己的文件或标记区块，而 waypoint rules --uninstall 会准确移除这些内容。
• 将日志簿设为私有 git 仓库，然后运行 waypoint refresh --push，即可拉取、重新绘制，只提交日志簿数据并推送。
• 从此仓库的克隆副本安装：python -m pip install -e .

哪些工具已接入

自动会话历史记录（使用了哪个项目、哪个工具、何时使用）仅来自 Claude Code 和 Codex。其他工具遵循规则，也能使用 MCP 工具，但它们的会话不会自动显示。

导航工具（AI CLI）	层级	Waypoint 接入内容
Claude Code	已支持	规则、本地 MCP 服务、会话事实
Codex（CLI 和桌面版）	已支持	规则、本地 MCP 服务、会话事实
Gemini CLI	预览版	规则、本地 MCP 服务
GitHub Copilot CLI	预览版	规则、本地 MCP 服务
Cursor、Windsurf、Kiro、Cline、Claude Desktop、Goose、opencode、Amp	配置片段	waypoint connect <cli> 会打印供粘贴的配置；不会写入任何内容
ChatGPT	Beacon	由你托管的远程 MCP 服务（升起信标）

• 规则会告诉工具在完成有意义的工作后添加一条日志记录。本地 MCP 服务（waypoint mcp，stdio）提供五个工具：take_fix（概览）、read_chart（单个项目）、log_watch（在锁保护下追加一条日志记录，并附上工具自身的 ID；提供 done/next 时，还会更新 Now 中的 Done、Next 和 Updated）、status（检查 Waypoint 是否已正确设置：仅显示状态和计数，不显示路径），以及 eod_report（当天的收工邮件，生成后只读）。它还提供三个提示词（在 Claude Code 中作为斜杠命令 /mcp__waypoint__<name>，在 Gemini CLI 中作为 /<name>）：where_am_i、log_this 和 send_eod。
• waypoint connect <cli> 可随时为所有项目接入一个 CLI。添加 --project <repo>（可重复使用）则只接入指定仓库：规则会写入仓库（作为导入项、指向日志簿规则的链接，或复制的内容块），MCP 条目也仅适用于该仓库；Waypoint 在那里创建的文件会通过 .git/info/exclude 排除在 git 之外。waypoint disconnect <cli> [--project <repo>] 只会移除 Waypoint 添加的内容。
• 如果某个 CLI 有自己的 mcp add 命令，就会通过该命令注册 MCP 服务（Codex 和 Copilot CLI 按仓库注册：Waypoint 会编辑它们的仓库文件）。如果已有其他服务使用 waypoint 这个名称，Waypoint 会以 waypoint-local 注册；--no-mcp 只安装规则。对于 Codex，Waypoint 还会询问是否将日志簿添加到其沙盒的 writable_roots 中（使用 --no-writable-root 可跳过）。
• waypoint rules 会报告每个工具的规则状态：同步、已偏离、缺失或被覆盖（Codex 实际读取的是 AGENTS.override.md）。
• 已知限制： Claude Code 默认会在 30 天后删除转录记录。Claude Code 和 Codex 的历史记录格式均为非官方格式；如果读取器出现问题，图表的来源健康状态会显示出来。

插件：提醒钩子

规则要求 Agent 记录日志；插件的钩子会提醒它。在会话开始时，Agent 会看到项目的 Now 和最新日志条目；如果一轮结束时仓库已更改而项目文件未更改，系统会提醒它记录一次（或说明没有内容需要记录）。钩子只负责提醒：日志条目仍由 Agent 编写。

先安装 Waypoint（pipx install waypoint-mcp，确保 waypoint 位于 PATH 中），运行 waypoint setup --no-mcp（或者在运行 waypoint setup 后，运行 waypoint connect <cli> --plugin，这会移除 setup 创建的独立 MCP 条目），然后：

CLI	安装
Claude Code	claude plugin marketplace add STiFLeR7/waypoint-mcp，然后运行 claude plugin install waypoint@waypoint-mcp
Codex	运行 codex plugin marketplace add STiFLeR7/waypoint-mcp、codex plugin add waypoint@waypoint-mcp，然后在 /hooks 中信任这些钩子（每次更新后也要再次信任）
Copilot CLI	copilot plugin install STiFLeR7/waypoint-mcp
Gemini CLI	gemini extensions install https://github.com/STiFLeR7/waypoint-mcp

如果你手动将 Waypoint 钩子写入某个工具自身的设置中，请在安装插件后将其移除，否则提醒可能会触发两次。

在 --tool auto 模式下，钩子通过插件环境变量区分工具（GEMINI_SESSION_ID、COPILOT_PLUGIN_ROOT、PLUGIN_ROOT、CLAUDE_PLUGIN_ROOT）；不要全局设置这些变量。

插件也会提供 MCP 服务，因此 waypoint connect <cli> --plugin 会移除 Waypoint 自己的独立 MCP 条目。waypoint status 会显示各工具上次运行钩子的时间。在 waypoint.toml 中关闭部分功能：[hooks] context = false、nudge = false，或 quiet = ["project"]。

每日结束邮件

可选功能。在一天结束时，让你的 AI 工具发送当天的报告：在 Claude Code 中输入 /mcp__waypoint__send_eod（如果 Waypoint 注册为 waypoint-local，则输入 /mcp__waypoint-local__send_eod），或在 Gemini CLI 中输入 /send_eod，也可以直接说“发送我的 EoD”。Waypoint 会根据你的日志簿（eod_report）生成邮件：一个适合邮件阅读的深色 HTML 页面及其纯文本版本，并附上 Waypoint 标志，包含今天日期下的每条日志。你的 AI 工具会通过 AgentMail 原样发送邮件，你只需连接一次 AgentMail。Waypoint 本身不会发送任何内容，也永远不会看到你的收件箱。

• waypoint setup 可以询问你的邮箱地址（默认选择 No；--yes 不会询问），也可以运行 waypoint email --to [email protected]。地址保存在一个本地文件中；运行 waypoint email --forget 可将其删除。
• waypoint email 会输出它找到的各个 AI 工具对应的 AgentMail 操作步骤，以及它记住的邮箱地址。
• ChatGPT：在同时启用了 Waypoint beacon 和 AgentMail 应用的聊天中输入“发送我的 EoD”。目前尚未确认能否在同一聊天中使用这两个应用。
• 邮件中绝不会包含提醒事项行；Waypoint 会自行将其排除。请参阅隐私。

阅读图表

图表内容	通俗含义
航程：航行中 / 滑行中 / 抛锚 / 入港	项目：活跃 / 偶尔进行 / 暂停 / 已完成
风险	- Attention: 行，以及已偏离的规则和无法读取的来源
未记录的值守	项目最新日志条目日期之后的 AI 会话
Now 落后于日志	## Now 的最近更新时间早于最新日志条目
漂流	闲置时间超过阈值（活跃项目为 21 天，偶尔进行的项目为 60 天）
未标注海域	有近期 AI 活动但没有项目文件的文件夹
港湾	projects/_archive/：已完成的航程，永不删除

Waypoint 绝不会更改项目的 Status、将项目归档或自行写入日志条目：它只会发出标记，由你来决定。

信号含义

• 活动表示某个工具操作过项目（会话、提交或日志条目）。这不代表实际完成了工作。
• 未记录的会话是从最新日志条目次日起开始的 Claude Code 和 Codex 会话。日志条目只记录日期，不记录时间，因此与某条目同一天稍晚进行的工作也算已记录。
• 当前状态落后于日志表示项目的 ## Now 上次更新（其 - Updated: 日期）早于最新日志条目，因此 上次进度 和 下一步 可能已过时。没有 Updated 行的项目永远不会显示此状态；传入 done/next 时，log_watch 会设置该日期。
• 日志条目记录的是某人写下的内容，不会验证代码。
• 可用上下文并不能证明 Agent 已阅读这些内容。
• 时效性：chart.html 和 DASHBOARD.md 是上次运行 waypoint refresh 时生成的快照。本地 MCP 服务实时读取日志簿（AI 活动最多缓存 30 秒）。Beacon 的仪表板字段以最近一次推送时的内容为准；其日志条目则实时读取。

隐私

• **任何内容都不会自行离开本机。**引擎没有监听器，不会发送网络请求，也不会收集遥测数据。--push 会针对你配置的远程仓库运行 git。
• 本地 MCP 服务只会向启动它的 AI 工具响应。该工具会像处理读取的其他内容一样，将结果发送给其模型提供商。结果包含项目名称、状态、Summary、Done、Next 和近期日志条目。除非 waypoint.toml 设置了 [mcp] include_attention = true，否则不会包含 Attention 行。会话标题、文件路径、未跟踪文件夹和动态信息流永远不会返回。
• **只有在你提出请求时，才会由 AI 工具通过 AgentMail（第三方服务）发送每日结束邮件。**地址保存在一个本地文件中，仅提供给运行 send_eod 的工具。详情请见：docs/PRIVACY.md。
• 日志文本是自由文本：你或你的工具写入的内容会随这些结果发送到相应位置。返回的文本只是提供给工具的数据，绝不是指令。

三个船体

船体	内容	位置
引擎	此仓库：规范、waypoint CLI、模板、测试	从 PyPI 安装
日志簿	你的数据：每个项目一个 Markdown 文件，另加图表	独立的私有 git 仓库
游乐场	实验和原型	随你放置

它们始终彼此隔离：引擎随软件一起发布，日志簿则归你所有。

升起信标

ChatGPT 不保留本地历史记录，也无法启动本地服务。信标（beacon/，高级功能）是你托管在 Cloudflare Workers 上、由 GitHub OAuth 保护的远程 MCP 服务，只响应你的 GitHub 账户。take_fix 和 read_chart 会读取图表；show_chart 会在 ChatGPT 和 Claude 内以卡片形式显示图表（MCP Apps）；log_watch 会向日志簿仓库追加一条 chatgpt 日志条目。设置需要 Cloudflare 账户、GitHub OAuth 应用和细粒度令牌：beacon/README.md。如果不使用信标，可将 ChatGPT 的摘要粘贴到项目文件中，作为一条 chatgpt 记录。

规范

日志簿格式、规则、图表的 JSON 以及所有访问约定都在 docs/LOGBOOK-SPEC.md 中（v1.5）。故事的术语表和风格则在 docs/STORY.md 中。

开发

python -m unittest                # stdlib only (the screen's tests skip)
python -m pip install -e ".[tui]" && python -m unittest   # with the screen's tests
python examples/build.py --check  # the example chart (Linux or macOS)
cd beacon && npm test             # the beacon

设计决策见 docs/decisions/；发布计划见 docs/release/R0-SCOPE.md。