Local Doc Annotator

Local Doc Annotator is a local review layer for Markdown preview and source files. It lets users open a workspace in a browser, add sidecar comments without changing source files, and then ask Codex to process those comments.

Phase 1 Scope

Supported:

• Markdown preview for .md and .markdown
• Source view for code, config, XML, BibTeX .bib, and common project files
• Plain text view for .txt, .log, .out, and .err
• Sidecar comments in .codex-annotations/comments.json
• Codex skill at .agents/skills/local-document-comments

Not supported in Phase 1:

• Word .doc / .docx
• PDF, PPTX, XLSX, standalone images, screenshots, notebooks
• LaTeX PDF preview, MDX, reStructuredText, AsciiDoc, HTML/SVG rendered annotation

Install From NPM

Run once without installing globally:

npx local-doc-annotator@latest --workspace /absolute/workspace/path --host 127.0.0.1 --port 4317

Or install the CLI globally:

npm install -g local-doc-annotator
local-doc-annotator --workspace /absolute/workspace/path --host 127.0.0.1 --port 4317

If you want Codex to process comments in future chats, install the bundled skill after the global npm install:

mkdir -p "$HOME/.agents/skills"
rm -rf "$HOME/.agents/skills/local-document-comments"
cp -R "$(npm root -g)/local-doc-annotator/.agents/skills/local-document-comments" "$HOME/.agents/skills/local-document-comments"

Start a new Codex chat or restart Codex if the skill is not detected immediately.

Run From Source

Install dependencies:

npm install

Start the annotator for the current directory:

npm run dev

Open a specific file:

http://127.0.0.1:4317/?file=README.md

The base URL stays available, but the current product flow expects Codex to open a file-specific preview link.

http://127.0.0.1:4317

Codex can present that as a Markdown link:

[README.md](http://127.0.0.1:4317/?file=README.md)

For a specific workspace:

npm run dev -- --workspace /absolute/workspace/path --host 127.0.0.1 --port 4317

For the bundled sample workspace:

npm run serve:example

Codex Setup Handoff

If another Codex user needs help setting up this project, give them docs/codex-setup-handoff.md. Codex can use that document to install the npm package globally, install the bundled skill into the user's global Codex skill directory, start the annotator, open a file-specific comment link, and process comments after the user adds them.

After setup and a new Codex chat or restart, prompts like this should trigger the installed skill:

I want to add comments to docs/review-notes. Give me a link for commenting.

Build

npm run build
npm start -- --workspace /absolute/workspace/path

Codex Workflow

After adding comments in the UI, ask Codex:

Use the local-document-comments skill. Read .codex-annotations/comments.json and process all open comments for README.md. Keep unrelated text unchanged.
Infer each comment's intent first. Answer explanation or review comments in the response, and edit files only when a comment asks for a content change.
Resolve comments after they are fully handled, and report the result in user-facing language without exposing internal ids or validation logs.

When asking a user to add comments, prefer sending a file link like [README.md](http://127.0.0.1:4317/?file=README.md) and tell them to open the preview, select text, and click Add comment.

Validation

npm test
npm run build
node .agents/skills/local-document-comments/scripts/validate-comments.mjs examples/workspace/.codex-annotations/comments.example.json

Data

Comments are stored under the selected workspace:

.codex-annotations/comments.json

The source files are not modified when comments are created.

中文说明

Local Doc Annotator 是一个本地文档批注工具。它会在浏览器里打开 Markdown、代码、配置文件和纯文本文件，让用户选中文本并添加 comment。创建 comment 时不会改原文件，批注数据会写到当前 workspace 下的 .codex-annotations/comments.json。之后可以让 Codex 读取这些 comment，并按 comment 的意图回答问题、修改文档或标记完成。

支持范围

当前支持：

• Markdown 预览：.md、.markdown
• 源码和配置文件
• BibTeX：.bib
• 纯文本：.txt、.log、.out、.err
• Codex skill：local-document-comments

当前不支持：

• Word、PDF、PPTX、XLSX
• 单独的图片和截图
• Codex 原生 Markdown 预览里的直接批注
• 渲染后的 HTML、SVG、MDX、reStructuredText、AsciiDoc

一行命令启动

不想全局安装时，可以直接用 npx 启动：

npx local-doc-annotator@latest --workspace /absolute/workspace/path --host 127.0.0.1 --port 4317

全局安装后，可以直接使用 local-doc-annotator 命令：

npm install -g local-doc-annotator
local-doc-annotator --workspace /absolute/workspace/path --host 127.0.0.1 --port 4317

让 Codex 后续 chat 也能处理 comment

如果希望以后在新的 Codex chat 里也能直接使用这个 skill，需要把 npm 包里的 skill 复制到 Codex 的全局 skill 目录：

mkdir -p "$HOME/.agents/skills"
rm -rf "$HOME/.agents/skills/local-document-comments"
cp -R "$(npm root -g)/local-doc-annotator/.agents/skills/local-document-comments" "$HOME/.agents/skills/local-document-comments"

如果 Codex 没有立刻识别到这个 skill，新开一个 chat 或重启 Codex。

给 Codex 的安装文档

可以直接把 docs/codex-setup-handoff.md 发给 Codex，并告诉它目标 workspace 和要批注的文件。这个 handoff 文档默认会指导 Codex 完成三件事，除非用户明确说只想临时使用：

• 通过 npm 全局安装 local-doc-annotator
• 把 local-document-comments 安装到 Codex 的全局 skill 目录
• 启动本地预览服务，并给用户一个可以添加 comment 的文件链接

用户添加 comment 后，回到 Codex 说“处理这些 comments”即可。Codex 会读取 .codex-annotations/comments.json，只处理 open comments，并根据 comment 的真实意图决定是回答、修改文件，还是标记完成。

安装完成并新开 chat 或重启 Codex 后，下面这种请求应该能触发已安装的 skill：

我想给 docs/review-notes 添加几条 comment，请给我一个批注链接。