commitmux (Blackwell Systems)

委员会

   

在git历史记录中进行关键字和语义搜索，作为编码代理的MCP工具公开。交叉回购，本地优先，无凭证，无利率限制。

代理可以按关键字搜索或用自然语言描述他们正在寻找的内容。你可以控制索引的内容。没有任何东西离开你的机器。

为什么选择commutmux

代理需要事先的工作环境：之前如何解决问题，某个领域发生了什么变化，哪些提交引入了模式。目前的选择很糟糕：

• 交给代理人 gh +代币 --无限制访问、速率限制、凭证暴露、仅限GitHub、无差异。
• 不要给代理人任何东西 --它会产生幻觉，或者你手动粘贴上下文。
• 自己粘贴上下文 --中断流，不缩放。

交叉仓库问题使情况变得更糟：当你维护20多个仓库并需要知道上个季度身份验证层发生了什么变化时， git log 要求您手动检查每个仓库。commitmux在单个查询中回答跨回购问题。

commitmux是第三种选择。它在您的提交历史上构建一个读取优化的本地索引，并将其作为一个狭窄的只读MCP工具界面公开。两种搜索模式协同工作：

• 全文搜索 （FTS5）——对提交主题、正文和补丁预览进行快速关键字搜索。
• 语义搜索 （向量嵌入）——自然语言查询，如“查找与速率限制相关的提交”或“与此描述类似的工作”。由任何兼容OpenAI的嵌入端点提供支持；开箱即用 奥拉玛 在本地运行。

索引位于您计算机上的单个SQLite文件中。MCP服务器作为代理主机的子进程运行。没有任何东西离开你的机器。

运作原理

commitmux使用libgit2遍历您的git历史记录（否 git 需要二进制文件），将提交存储在SQLite中，对主题、正文和补丁预览进行FTS5全文索引，并使用zstd压缩原始差异。语义搜索将float32嵌入与提交元数据一起存储——余弦相似度是在没有外部向量数据库的情况下在进程中计算的。MCP服务器通过stdio传输JSON-RPC 2.0；代理主机将其作为子进程运行，八个只读工具对代理可用。

快速开始

基本设置

# 1. Build and install
cargo install --path .

安装后，确保 ~/.cargo/bin 在您的路径上：

# Add to your shell profile (~/.zshrc, ~/.bashrc, etc.)
source "$HOME/.cargo/env"

或添加 export PATH="$HOME/.cargo/bin:$PATH" 直接添加到您的shell配置文件。

# 2. Create the database
commitmux init

# 3. Register repos — local paths or remote URLs
commitmux add-repo ~/code/myproject
commitmux add-repo ~/code/anotherproject --name another

# Remote repos are auto-cloned to ~/.commitmux/clones//
commitmux add-repo --url git@github.com:org/repo.git

# 4. Ingest commits (fetches from remote first for URL-based repos)
commitmux sync

之后 sync，关键字搜索索引已准备就绪。配置您的代理主机以运行 commitmux serve （参见 MCP主机设置)并且MCP工具对代理可用。

启用语义搜索（可选）

语义搜索允许代理通过自然语言而不是关键字进行查询。需要任何与OpenAI兼容的嵌入端点——开箱即用 奥拉玛 在本地运行。

ollama pull nomic-embed-text
commitmux config set embed.model nomic-embed-text
commitmux add-repo ~/code/myproject --embed   # or: commitmux update-repo myproject --embed
commitmux sync --embed-only                   # backfill embeddings for existing commits

要改用托管提供程序，请执行以下操作：

commitmux config set embed.endpoint https://api.openai.com/v1
commitmux config set embed.model text-embedding-3-small

启动MCP服务器

# stdio transport — run by your agent host, not manually in a terminal
commitmux serve

行动中

MCP服务器运行后，代理可以直接查询您的git历史记录。两个例子：

“我们以前实施过利率限制吗？”

代理人打电话来 commitmux_search 随着 query: "rate limiting".commitmux返回带有补丁摘录的匹配提交。代理人打电话来 commitmux_get_patch 在最相关的SHA上阅读完整的差异。它建立在之前的实现之上，而不是从头开始。

“上个月所有存储库的身份验证层发生了什么变化？”

代理人打电话来 commitmux_touches 随着 path_glob: "auth/" 以及a since 时间戳。commitmux返回每个索引仓库的提交-- api-server, auth-service, web-frontend --在一个回应中。不在仓库之间切换，不粘贴 git log 输出，无令牌暴露。

“查找与背压和重试逻辑相关的提交” （语义搜索）

代理人打电话来 commitmux_search_semantic 使用该自然语言查询。commitmux嵌入查询并通过向量相似性返回提交——即使提交消息中没有出现确切的单词，也会显示相关的工作。

记忆搜索

commitmux还为claudewatch内存文件建立索引，以进行语义和关键字搜索。这使代理可以访问之前的会话摘要、任务历史、阻止程序和决策，而不仅仅是提交历史。

设置：

# Index memory files manually (or let install-memory-hook do it automatically)
commitmux ingest-memory

# Install the Stop hook to auto-ingest after every Claude Code session
commitmux install-memory-hook

用法（通过MCP）：

一旦内存被索引 commitmux_search_memory MCP工具可供代理商使用。当Ollama不可用时，它通过自动FTS5回退按含义（语义）搜索：

{
  "name": "commitmux_search_memory",
  "arguments": {
    "query": "how did we implement rate limiting",
    "project": "api-server"
  }
}

内存文档有源类型： session_summary, task, blocker, decision, memory_file, impl_doc.筛选条件 source_type 缩小结果。

CLI参考

所有子命令均接受 --db 以覆盖数据库位置。看 配置 用于路径分辨率顺序。

init

创建数据库和架构。Idempotent——可以再次安全奔跑。

commitmux init
commitmux init --db /data/commitmux.sqlite3

add-repo

注册一个git仓库。通过接受本地路径或远程URL --url。仓库名称默认为目录名称（本地路径）或存储库基名称（URL）。

commitmux add-repo 
 [--name ] [--exclude 
]...
commitmux add-repo --url  [--name ] [--exclude 
]...

# Use directory name as repo name
commitmux add-repo ~/code/myproject

# Override the name
commitmux add-repo ~/code/myproject --name myproject

# Exclude additional path prefixes on top of the defaults
commitmux add-repo ~/code/myproject --exclude generated/ --exclude proto/

# Add a remote repo (auto-clones to ~/.commitmux/clones// on first sync)
commitmux add-repo --url git@github.com:org/repo.git

# Add a remote repo over HTTPS
commitmux add-repo --url https://github.com/org/repo.git --name repo

通过 --embed 为仓库启用语义嵌入。嵌入是在以下过程中生成的 sync 使用配置的模型。

# Enable embeddings on registration
commitmux add-repo ~/code/myproject --embed

# Add a remote repo with embeddings
commitmux add-repo --url git@github.com:org/repo.git --embed

这 --exclude 标志附加到默认忽略列表。默认忽略前缀： node_modules/, vendor/, dist/, .git/.

SSH远程使用SSH代理进行身份验证。确保您的SSH代理正在运行并已加载相关密钥(ssh-add)跑步前 sync 针对SSH URL。

update-repo

更新已注册存储库的配置。使用此选项可启用或禁用在配置语义搜索之前添加的仓库上的嵌入。

commitmux update-repo  [--embed] [--no-embed]

# Enable embeddings on an existing repo
commitmux update-repo myproject --embed

# Disable embeddings
commitmux update-repo myproject --no-embed

启用嵌入后，运行 commitmux sync --embed-only 以回填现有的提交。

sync

从所有已注册的仓库或单个仓库中摄取提交。可以安全地重新运行——出现故障 (repo, sha).

commitmux sync
commitmux sync --repo myproject
commitmux sync --embed-only   # generate embeddings only; skip re-ingesting commits

Ingestion仅遍历默认分支。如果补丁超过1 MB或仅包含二进制差异，则跳过提交。跑 sync 再次在任何时候获取新的提交。

对于已注册的repos --url, sync 自动从远程获取行走前的历史记录。不需要额外的标志——一个简单的 commitmux sync 使基于URL的存储库保持最新。

摄入后，会自动为任何具有以下特征的repo生成嵌入 --embed 启用。使用 --embed-only 在不重新遍历历史的情况下回填嵌入（例如，在已经同步的仓库上启用嵌入后）。

show

以JSON格式打印单个提交。可用于调试或验证摄取。

commitmux show  
commitmux show myproject a3f9c12

输出与 commitmux_get_commit MCP工具响应准确。

status

打印一个包含所有已注册存储库的表，其中包含提交计数和上次同步时间。

commitmux status

REPO                  COMMITS  SOURCE                                             LAST SYNCED             EMBED
myproject                2341  /Users/you/code/myproject                         2026-02-28 14:03:17 UTC  ✓
another                   892  https://github.com/org/another.git                2026-02-28 14:03:51 UTC  -

Embedding model: nomic-embed-text (http://localhost:11434/v1) — ✓ = enabled

config

读取和写入命名配置值。主要用于配置嵌入模型和端点。

commitmux config get 
commitmux config set  

支持的密钥：

# Use a different Ollama model
commitmux config set embed.model mxbai-embed-large

# Point at a remote OpenAI-compatible endpoint
commitmux config set embed.endpoint https://api.openai.com/v1
commitmux config set embed.model text-embedding-3-small

配置存储在数据库中。值在命令之间保持不变。

install-hook

在调用以下命令的存储库中安装一个提交后git挂钩 commitmux sync 每次承诺之后。无需人工干预即可保持索引新鲜。

commitmux install-hook 

commitmux install-hook ~/code/myproject
commitmux install-hook ~/code/myproject --force   # overwrite existing hook

--force 覆盖现有的钩子。如果没有它，该命令会打印一个警告，如果钩子已经存在，则退出。

install-memory-hook

注册 commitmux ingest-memory 作为克劳德代码停止挂钩 ~/.claude/settings.json安装后，内存文件会在每个Claude Code会话结束时自动摄取和嵌入。

commitmux install-memory-hook
commitmux install-memory-hook --db /data/commitmux.sqlite3
commitmux install-memory-hook --claude-settings /path/to/settings.json

重复防护：如果 commitmux ingest-memory 如果已注册，该命令将打印“已安装”并退出，而不修改文件。

ingest-memory

扫描 ~/.claude/projects/*/memory/*.md 并索引内存文档以进行语义搜索。增量-仅重新嵌入自上次摄取以来发生更改的文件。

commitmux ingest-memory
commitmux ingest-memory --claude-home /path/to/.claude
commitmux ingest-memory --db /data/commitmux.sqlite3

index-impl-docs

SAW协议IMPL文档索引(docs/IMPL/IMPL-*.md)从工作树到内存搜索索引。使代理能够按内容搜索之前的计划文档。

commitmux index-impl-docs 

commitmux index-impl-docs ~/code/myproject
commitmux index-impl-docs ~/code/myproject --project myproject

--project 用项目名称（默认为目录名）标记索引文档。

reindex

删除一个或所有存储库的所有嵌入，然后从头开始重新嵌入。在切换嵌入模型或批量历史导入后使用。

commitmux reindex
commitmux reindex --repo myproject
commitmux reindex --reset-dim   # prints advisory to manually clear embed.dimension

--reset-dim 用于切换嵌入模型。目前打印补救建议，而不是自动清除存储的维度--使用 commitmux config set embed.dimension "" 如果需要的话。

serve

在stdio上启动MCP服务器。这是代理主机运行的命令，不打算在终端中直接调用。

commitmux serve
commitmux serve --db /data/commitmux.sqlite3

服务器从stdin读取换行符分隔的JSON-RPC，并将响应写入stdout。它一直运行到stdin关闭。

在启动时， commitmux serve 检查每个索引仓库 last_synced_at 并自动同步过去一小时内未同步的任何仓库。输出转到stderr以避免污染MCP stdout。

MCP工具参考

服务器公开了八个工具。所有工具都是只读的。

commitmux_search_semantic

使用向量相似度对提交历史进行自然语言语义搜索。当关键字搜索不足时使用，例如“查找与错误处理相关的提交”或“与此描述类似的工作”。仅返回启用嵌入的repos的结果。

需要任何与OpenAI兼容的嵌入端点。开箱即用 奥拉玛 在本地运行；支持OpenAI和任何兼容的提供商。配置为 commitmux config set embed.endpoint 和 commitmux config set embed.model .

输入架构：

示例调用：

{
  "name": "commitmux_search_semantic",
  "arguments": {
    "query": "rate limiting and backpressure",
    "repos": ["api-server"],
    "limit": 5
  }
}

输出示例：

[
  {
    "repo": "api-server",
    "sha": "a3f9c12b4e77d",
    "subject": "Add token bucket rate limiter to middleware stack",
    "author": "Dayna Blackwell",
    "date": 1740700997,
    "score": 0.91,
    "patch_excerpt": "diff --git a/src/middleware/rate_limit.rs ..."
  }
]

结果包括a score 字段（0-1）表示与查询的相似性。越高越相似。

commitmux_search

对提交主题、正文和补丁预览（每个差异的前2000个字符）进行全文搜索。使用SQLite FTS5。

输入架构：

示例调用：

{
  "name": "commitmux_search",
  "arguments": {
    "query": "rate limiting middleware",
    "repos": ["api-server"],
    "limit": 5
  }
}

输出示例：

[
  {
    "repo": "api-server",
    "sha": "a3f9c12b4e77d",
    "subject": "Add token bucket rate limiter to middleware stack",
    "author": "Dayna Blackwell",
    "date": 1740700997,
    "matched_paths": ["src/middleware/rate_limit.rs", "src/middleware/mod.rs"],
    "patch_excerpt": "diff --git a/src/middleware/rate_limit.rs b/src/middleware/rate_limit.rs\nnew file mode 100644\n+use std::sync::Arc;\n+use tokio::sync::Semaphore;"
  }
]

commitmux_touches

查找涉及特定文件或路径模式的提交。在存储的路径上使用子字符串匹配。

输入架构：

示例调用：

{
  "name": "commitmux_touches",
  "arguments": {
    "path_glob": "src/auth/",
    "since": 1735689600
  }
}

输出示例：

[
  {
    "repo": "api-server",
    "sha": "b8c21d3f9a",
    "subject": "Migrate auth tokens to short-lived JWTs",
    "date": 1740611200,
    "path": "src/auth/tokens.rs",
    "status": "M"
  },
  {
    "repo": "api-server",
    "sha": "c4e87f2110",
    "subject": "Add refresh token rotation",
    "date": 1739900000,
    "path": "src/auth/refresh.rs",
    "status": "A"
  }
]

文件状态值： A （已添加）， M （已修改）， D （已删除）， R （重命名）， C （复制）。

commitmux_get_commit

检索特定提交的完整元数据，包括已更改文件的列表。

输入架构：

示例调用：

{
  "name": "commitmux_get_commit",
  "arguments": {
    "repo": "api-server",
    "sha": "a3f9c12b4e77d"
  }
}

输出示例：

{
  "repo": "api-server",
  "sha": "a3f9c12b4e77d831290ab45c6de1f8e3",
  "subject": "Add token bucket rate limiter to middleware stack",
  "body": "Fixes #482. Uses a per-IP token bucket with a 100 req/min default.\nBucket capacity and refill rate are configurable via environment variables.",
  "author": "Dayna Blackwell",
  "date": 1740700997,
  "changed_files": [
    { "path": "src/middleware/rate_limit.rs", "status": "A", "old_path": null },
    { "path": "src/middleware/mod.rs", "status": "M", "old_path": null },
    { "path": "tests/middleware_test.rs", "status": "M", "old_path": null }
  ]
}

commitmux_get_patch

检索提交的原始统一差异。补丁在检索时以zstd压缩和解压缩的方式存储。使用 max_bytes 在处理大型提交时限制响应大小。

输入架构：

示例调用：

{
  "name": "commitmux_get_patch",
  "arguments": {
    "repo": "api-server",
    "sha": "a3f9c12b4e77d",
    "max_bytes": 8000
  }
}

输出示例：

{
  "repo": "api-server",
  "sha": "a3f9c12b4e77d831290ab45c6de1f8e3",
  "patch_text": "diff --git a/src/middleware/rate_limit.rs b/src/middleware/rate_limit.rs\nnew file mode 100644\nindex 0000000..f3a2c81\n--- /dev/null\n+++ b/src/middleware/rate_limit.rs\n@@ -0,0 +1,47 @@\n+use std::sync::Arc;\n+..."
}

在摄取时补丁大于1 MB的提交将跳过其补丁。仅二进制的差异也被跳过。 commitmux_get_commit 仍将返回这些提交的元数据和文件列表。

commitmux_search_memory

对claudewatch内存文件（会话摘要、任务、阻止程序、决策）进行语义搜索。使代理能够按意义在所有项目中找到先前的上下文和解决方案。如果嵌入服务（Ollama）不可用，则自动返回FTS5关键字搜索。

输入架构：

示例调用：

{
  "name": "commitmux_search_memory",
  "arguments": {
    "query": "how did we implement rate limiting",
    "project": "api-server"
  }
}

commitmux_search_saw

按功能名称和可选波数搜索SAW（Scout和Wave）协议合并提交的提交历史。在内部构造正确的FTS5查询。

输入架构：

示例调用：

{
  "name": "commitmux_search_saw",
  "arguments": {
    "feature": "memory search",
    "wave": 2
  }
}

配置

数据库路径按以下顺序解析：

1. `--db

` 标志（优先于一切）

1. COMMITMUX_DB 环境变量
2. ~/.commitmux/db.sqlite3 （默认）

# Flag
commitmux sync --db /data/mydb.sqlite3

# Environment variable
export COMMITMUX_DB=/data/mydb.sqlite3
commitmux sync

# Default — no configuration needed
commitmux sync

MCP主机设置

克劳德桌面版

将commitmux添加到 claude_desktop_config.json。该文件通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上。

{
  "mcpServers": {
    "commitmux": {
      "command": "commitmux",
      "args": ["serve"]
    }
  }
}

如果 commitmux 二进制文件不在Claude Desktop的PATH中，请使用完整路径：

{
  "mcpServers": {
    "commitmux": {
      "command": "/Users/you/.cargo/bin/commitmux",
      "args": ["serve"]
    }
  }
}

要使用非默认数据库，请执行以下操作：

{
  "mcpServers": {
    "commitmux": {
      "command": "commitmux",
      "args": ["serve", "--db", "/data/commitmux.sqlite3"]
    }
  }
}

其他MCP主机

任何支持stdio传输的MCP主机都可以运行commitlux。服务器命令为 commitmux serve.它讲MCP协议版本 2024-11-05 以换行符分隔的JSON-RPC 2.0形式通过stdin/stdout传输。

通用主机配置示例：

{
  "command": "commitmux",
  "args": ["serve"],
  "transport": "stdio"
}

看 docs/mcp.md 完整的MCP集成参考，包括安全模型、新鲜度考虑和原始协议示例。

实现注意事项

• 用途 git2 （libgit2绑定）用于提交摄入。不 git 需要二进制文件。
• 补丁存储为zstd压缩blob（级别3）。FTS5索引包括主题、正文和每个补丁的前2000个字符。
• SQLite WAL模式已启用。在并发同步期间，数据库的读取是安全的。
• MCP服务器是同步的（没有异步运行时）。每个请求都在主线程上内联处理。
• 嵌入作为原始float32 blob与提交元数据一起存储在SQLite中。相似性搜索使用过程中计算的余弦距离，不需要单独的向量数据库。
• 嵌入API调用使用 异步openai 针对任何与OpenAI兼容的 /v1/embeddings 终点。与Ollama、OpenAI和兼容提供商合作。