Agentic Nix

代理nix

Claude的混合代码搜索。将您的代码库、文档和GitHub问题编入索引 PostgreSQL（ParadeDB BM25+pgvector HNSW）。Rust MCP服务器将索引暴露给Claude代码 因此，它可以回答有关代码的问题，而无需从头开始读取每个文件。

这取代了什么： 克劳德一个接一个地阅读了50个文件，找到了一些东西。相反，克劳德 使用单个工具调用查询索引，并在一秒钟内获取10个最相关的块。

______________________________________________________________________

运作原理

your repos ──► ingest ──► PostgreSQL (ParadeDB)
                               │
                          BM25 + vector          Ollama
                          hybrid search    ◄──  embeddings
                               │
                          MCP server ──► Claude Code

1. 这 ingest 二进制遍历你的存储库，通过树形图提取命名符号，嵌入每个符号

并将所有内容存储在PostgreSQL中。

1. 这 mcp-server 二进制文件位于Claude和数据库之间，公开了搜索工具

MCP协议（stdio）。

1. Claude Code会自动连接到MCP服务器，并在需要时调用工具

理解代码。

______________________________________________________________________

先决条件

• 尼克斯 启用薄片
• Git

就是这样。PostgreSQL、Ollama、Rust和所有其他工具都由Nix管理。

启用薄片 如果您还没有添加到 ~/.config/nix/nix.conf:

experimental-features = nix-command flakes

在Ubuntu或其他非NixOS系统上？ nix run .#dev 不会使用您的GPU--CUDA库 NixOS外部的Nix封装Ollama的路径解析不正确。看 非NixOS/Ubuntu设置 下面是系统服务的替代方案。

______________________________________________________________________

非NixOS/Ubuntu设置

在Ubuntu上，使用系统管理的PostgreSQL和Ollama。Nix-dev shell仍然提供Rust 工具链， just，以及所有构建工具——只有服务不同。

1.使用ParadeDB和pgvector安装PostgreSQL 17

如果你还没有添加PostgreSQL apt仓库：

sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

安装 pg_search （ParadeDB BM25）和pgvector：

# ParadeDB repo
curl -fsSL https://apt.fury.io/paradedb/gpg.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/paradedb.gpg
echo "deb [signed-by=/usr/share/keyrings/paradedb.gpg] https://apt.fury.io/paradedb/ stable main" \
  | sudo tee /etc/apt/sources.list.d/paradedb.list

sudo apt update
sudo apt install -y postgresql-17-pg-search postgresql-17-pgvector

启用 pg_search 在PostgreSQL中--添加到 /etc/postgresql/17/main/postgresql.conf:

shared_preload_libraries = 'pg_search'
pg_search.enable_telemetry = off

重新启动PostgreSQL：

sudo systemctl restart postgresql

创建数据库并应用架构：

sudo -u postgres createdb codebase
sudo -u postgres psql codebase -c \
  "CREATE EXTENSION IF NOT EXISTS pg_search; CREATE EXTENSION IF NOT EXISTS vector;"

# Allow your user to connect (adjust if you use password auth instead)
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE codebase TO $USER;"
sudo -u postgres psql codebase -c "GRANT ALL ON SCHEMA public TO $USER;"

# Enter the Nix dev shell, then apply the schema
nix develop
just migrate

2.安装Olama

官方安装程序会自动检测CUDA：

curl -fsSL https://ollama.com/install.sh | sh

拉动嵌入模型：

ollama pull hf.co/jinaai/jina-code-embeddings-1.5b-GGUF:Q8_0

Ollama作为systemd服务运行，并在启动时启动。使用验证GPU使用情况 ollama ps 之后 拉一个模型——它应该显示 GPU 在处理器列中。

3.继续正常设置

跳过 nix run .#dev step--您的服务已经在运行。直接跳到 构建Rust二进制文件 并从那里继续。一切 其他（索引、MCP注册、Claude集成）是相同的。

______________________________________________________________________

首次设置

1.克隆并进入开发shell

git clone  ~/agentic-nix
cd ~/agentic-nix
nix develop

第一 nix develop 下载Rust、PostgreSQL、Ollama和所有依赖项。这需要 几分钟一次；后续的壳是即时的。

2.构建Rust二进制文件

just build

这产生 target/release/mcp-server 和 target/release/ingest你只需要 当Rust源代码更改时进行重建。

3.启动服务

在专用终端中（保持其运行）：

nix run .#dev

这将开始：

• PostgreSQL 17 上 localhost:5432 和 pg_search （BM25）和 pgvector （HNSW）已加载。

这 codebase 数据库是使用完整模式自动创建的。

• 奥拉玛 上 localhost:11434 随着 jina-code-embeddings-1.5b 模型拉。

首次启动拉动模型（~1.5 GB）；后续启动是即时的。

数据存储在 ./data/ 相对于您运行命令的位置，因此始终从以下位置运行它 回购根。

4.确认一切正常运行

# Should return a connection
just psql

# Should return empty tables (schema applied automatically)
just stats

______________________________________________________________________

为代码编制索引

为代码库建立索引

just index /path/to/your/repo

这将遍历仓库，提取TypeScript、JavaScript、Python、Rust和Haskell的符号 使用树状图（函数、类、结构等）的文件，并回退到重叠 其他文件类型的行窗口。跳过自上次运行以来未更改的文件。

从头开始重新索引所有内容：

just reindex /path/to/your/repo

索引多个仓库——每个仓库只需运行一次命令：

just index ~/work/frontend
just index ~/work/backend
just index ~/work/infrastructure

索引文档

发现 AGENTS.md, CLAUDE.md, README.md，以及任何 .agent/workflows/, .agent/skills/, .agent/plans/, .agent/SOPs/ 标记文件：

just index-docs /path/to/your/repo

索引GitHub问题和拉取请求

export GITHUB_TOKEN=ghp_...   # optional but recommended (5000 req/hr vs 60)
just index-github anthropics/claude-code

这将获取所有问题、PR及其评论。后续运行是增量的，仅包含项目 自上次同步以来已更新。

仅索引特定流：

just index-github-issues anthropics/claude-code   # issues only
just index-github-prs    anthropics/claude-code   # PRs only

检查索引内容

just stats          # row counts per table
just sync-status    # GitHub watermarks (last sync times)

______________________________________________________________________

连接到克劳德代码

MCP服务器通过stdio与Claude Code通信。你需要注册一次。

添加MCP服务器

从运行此 ~/agentic-nix 目录：

claude mcp add agentic-nix \
  --command "$(pwd)/target/release/mcp-server" \
  --env PG_DSN=postgresql://127.0.0.1:5432/codebase \
  --env OLLAMA_HOST=http://127.0.0.1:11434

或者手动将其添加到您的Claude Code配置中(~/.claude.json 或项目 .claude/mcp.json):

{
  "mcpServers": {
    "agentic-nix": {
      "command": "/home/you/agentic-nix/target/release/mcp-server",
      "env": {
        "PG_DSN": "postgresql://127.0.0.1:5432/codebase",
        "OLLAMA_HOST": "http://127.0.0.1:11434"
      }
    }
  }
}

验证连接

启动一个新的Claude Code会话并询问：

List all indexed repositories.

克劳德应该打电话来 list_repos 并返回您已索引的repos。如果它无法连接， 检查服务是否正在运行(nix run .#dev)并且二进制路径是正确的。

______________________________________________________________________

与Claude一起使用索引

克劳德如何自动使用这些工具

一旦连接，Claude将在需要了解时自动调用搜索工具 你的代码。你不必做任何特别的事情，只要正常工作就行了。例如：

• *“身份验证中间件是如何工作的？”* → Claude搜索与身份验证相关的代码
• *“为什么添加此API终结点？”* → Claude在GitHub问题中搜索上下文
• *“什么是 UserService 类做？"* → 克劳德为那个符号取块

从索引中获得最大收益的提示

明确帮助克劳德知道搜索而不是猜测：

Search the codebase for how we handle database connection pooling.

Look through the indexed GitHub issues for any discussion of rate limiting.

Find all the Rust functions related to embedding and explain how they fit together.

Search the docs for our deployment workflow.

可用工具

您可以引导Claude使用特定的工具：

Use bm25_search to find every place we call `send_email`.

Search GitHub PRs for anything related to the login refactor.

Search only Haskell files for the `parseConfig` function.

过滤器

搜索工具接受您可以在提示中提及的可选过滤器：

• 语言: search in Rust files, TypeScript only
• 符号种类: only functions, find all classes, interfaces only
• 文件类型: search workflows, look in SOPs
• GitHub: open issues only, only PRs, in the anthropics/claude-code repo

______________________________________________________________________

保持指数最新

拉取新代码后

重新索引是增量的——只处理更改的文件：

just index /path/to/your/repo

计划重新索引（可选）

添加到crontab或systemd计时器：

# Re-index at 2am every night
0 2 * * * cd ~/agentic-nix && nix develop --command just index ~/work/myrepo

经过大规模重构

如果你移动了很多文件，完整的重新索引会更清晰：

just reindex /path/to/your/repo

______________________________________________________________________

环境变量

所有变量都有合理的默认值；根据需要进行覆盖。

______________________________________________________________________

快速查阅

# Services
nix run .#dev                          # start PostgreSQL + Ollama

# Binaries
just build                             # build mcp-server + ingest

# Indexing
just index /path/to/repo               # code (incremental)
just reindex /path/to/repo             # code (force full re-index)
just index-docs /path/to/repo          # markdown docs
just index-github OWNER/REPO           # GitHub issues + PRs
just reindex-github OWNER/REPO         # GitHub (ignore watermarks)

# Inspection
just stats                             # row counts
just sync-status                       # GitHub watermarks
just psql                              # open a psql session

# Schema
just migrate                           # apply schema.sql (safe to re-run)

______________________________________________________________________

故障排除

“嵌入失败（Ollama在跑步吗？）” MCP服务器无法连接到Ollama。确保 nix run .#dev 正在运行，或检查 OLLAMA_HOST 指向正确的地址。

“数据库错误：连接被拒绝” PostgreSQL没有运行。从以下内容开始 nix run .#dev.数据存在 ./data/pg/ — 您必须从repo根目录运行，以便正确解析路径。

克劳德不调用搜索工具 Claude并不总是主动使用MCP工具。明确： *“搜索索引 的代码库。.."* 或 *“使用搜索工具查找…”*.

启动后第一次查询速度慢 嵌入模型在第一个请求时延迟加载。后续查询很快。

GitHub速率限制命中 集 GITHUB_TOKEN 使用个人访问令牌。未授权限制为60个请求/小时； 经过身份验证的是5000/小时。

Ollama在Ubuntu上使用CPU而不是GPU Nix打包的Ollama无法在NixOS之外解析CUDA库。使用Ollama安装程序 相反，请参见 非NixOS/Ubuntu设置确认GPU已激活 ollama ps 同时加载模型。