Clawmarks
Storybook-style annotated bookmarks for code exploration.
问题
在复杂问题上使用LLM代理通常意味着迭代多个文件，考虑替代方案，做出决策，并随着时间的推移建立理解。但当对话结束时，你会留下一堵聊天历史记录墙和修改过的文件——没有明确的线索 *哪里* 你去了 *为什么*.
Clawmarks通过让代理在工作时删除带注释的书签来解决这个问题。这些爪标捕捉了您的探索过程：决策点、未决问题、考虑的替代方案以及它们之间的联系方式。结果是您的编码会话的可导航地图，而不仅仅是成绩单。
它做什么
Clawmarks是一个MCP服务器，它为LLM代理提供了在代码库中创建带注释书签的工具。Clawmarks被组织成轨迹（叙事旅程），可以相互引用（知识图风格），并存储在任何编辑器都可以使用的简单JSON文件中。
每个爪痕都捕捉到：
- 哪里 -文件、行、列
- 什么 -解释此位置为何重要的注释
- 类型 -决策、问题、所需变更、替代方法等。
- 连接 -参考其他抓痕（知识图边缘）
- 上下文 -标签和轨迹分组
快速开始
- 全局安装：
npm install -g clawmarks- 添加
.clawmarks.json到您的全局gitignore（一次性设置）：
echo ".clawmarks.json" >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global- 添加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 | 欢迎投稿 |
示例用法
在与您的法学硕士代理人的对话中：
“让我们探索两种重构身份验证系统的方法。你能创建一条线索并标记关键决策点吗？”
代理人将：
- 创建一个名为“身份验证重构选项”的跟踪
- 在相关代码位置添加抓痕
- 将相关爪痕链接在一起
- 标记带有相关问题的抓痕
然后，您可以在编辑器中浏览这些抓痕，以重新审视代码中的探索之旅。
许可证
麻省理工学院