AI导哈

代码注释书签工具

Clawmarks是一个为LLM代理设计的代码注释书签工具，通过创建和组织书签来记录代码探索过程中的决策点和问题，形成可导航的代码会话地图。

  • by mrilikecoding
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 mrilikecoding/clawmarks

使用说明

Clawmarks

Storybook-style annotated bookmarks for code exploration.

问题

在复杂问题上使用LLM代理通常意味着迭代多个文件，考虑替代方案，做出决策，并随着时间的推移建立理解。但当对话结束时，你会留下一堵聊天历史记录墙和修改过的文件——没有明确的线索 哪里 你去了 为什么.

Clawmarks通过让代理在工作时删除带注释的书签来解决这个问题。这些爪标捕捉了您的探索过程：决策点、未决问题、考虑的替代方案以及它们之间的联系方式。结果是您的编码会话的可导航地图，而不仅仅是成绩单。

它做什么

Clawmarks是一个MCP服务器，它为LLM代理提供了在代码库中创建带注释书签的工具。Clawmarks被组织成轨迹（叙事旅程），可以相互引用（知识图风格），并存储在任何编辑器都可以使用的简单JSON文件中。

每个爪痕都捕捉到：

  • 哪里 -文件、行、列
  • 什么 -解释此位置为何重要的注释
  • 类型 -决策、问题、所需变更、替代方法等。
  • 连接 -参考其他抓痕（知识图边缘）
  • 上下文 -标签和轨迹分组

快速开始

  1. 全局安装：

    npm install -g clawmarks

  2. 添加 .clawmarks.json 到您的全局gitignore（一次性设置）：

    echo ".clawmarks.json" >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global

  3. 添加MCP服务器：

    选项A:Claude CLI（推荐）

    claude mcp add --scope user clawmarks -- clawmarks mcp

    选项B：手动配置

    添加到您的项目 .mcp.json:

    {
  "mcpServers": {
    "clawmarks": {
      "command": "clawmarks",
      "args": ["mcp"]
    }
  }
}

服务器存储 .clawmarks.json 在当前工作目录中。要覆盖项目根目录，请执行以下操作：

claude mcp add --scope user clawmarks -- clawmarks mcp --env CLAWMARKS_PROJECT_ROOT=/path/to/project

或在 .mcp.json:

{
  "mcpServers": {
    "clawmarks": {
      "command": "clawmarks",
      "args": ["mcp"],
      "env": {
        "CLAWMARKS_PROJECT_ROOT": "/path/to/project"
      }
    }
  }
}

MCP工具

步道管理

工具 说明
create_trail 创建新的痕迹来组织相关的爪痕
list_trails 列出所有轨迹（可选择按状态筛选）
get_trail 获取所有爪痕的踪迹细节
archive_trail 将已完成的踪迹存档

爪标管理

工具 说明
add_clawmark 在文件位置添加带注释的书签
update_clawmark 更新爪标元数据
delete_clawmark 去除爪痕
list_clawmarks 列出带有可选过滤器的抓痕

知识图谱

工具 说明
link_clawmarks 创建从一个爪标到另一个爪标记的引用
unlink_clawmarks 删除引用
get_references 将所有爪痕连接到一个爪痕
list_tags 列出在抓痕中使用的所有标签

爪标类型

  • decision -已作出的决定点
  • question -需要解决的未决问题
  • change_needed -需要修改的代码
  • reference -参考点（理解现有代码）
  • alternative -正在考虑替代方法
  • dependency -这取决于什么

数据格式

Clawmarks将数据存储在 .clawmarks.json:

{
  "version": 1,
  "trails": [
    {
      "id": "t_abc123",
      "name": "Auth Refactor Options",
      "description": "Exploring JWT vs session-based auth",
      "status": "active",
      "created_at": "2025-12-17T10:30:00Z"
    }
  ],
  "clawmarks": [
    {
      "id": "c_xyz789",
      "trail_id": "t_abc123",
      "file": "src/auth/handler.ts",
      "line": 42,
      "column": 8,
      "annotation": "Current session logic - could replace with JWT",
      "type": "alternative",
      "tags": ["#security", "#breaking-change"],
      "references": ["c_def456"],
      "created_at": "2025-12-17T10:31:00Z"
    }
  ]
}

编辑器集成

这 .clawmarks.json 该文件旨在供任何编辑器或工具使用。

编辑器 插件
我不知道。 爪标.nvim
VS代码 即将推出
Emacs 欢迎投稿

示例用法

在与您的法学硕士代理人的对话中：

“让我们探索两种重构身份验证系统的方法。你能创建一条线索并标记关键决策点吗？”

代理人将：

  1. 创建一个名为“身份验证重构选项”的跟踪
  2. 在相关代码位置添加抓痕
  3. 将相关爪痕链接在一起
  4. 标记带有相关问题的抓痕

然后，您可以在编辑器中浏览这些抓痕，以重新审视代码中的探索之旅。

许可证

麻省理工学院

相关 MCP