convez.ai
MCP ServerBusca & PesquisaAvançado
sivru

Sivru — Camada de Compreensão para Código IA

sivru/sivru

Busca + observabilidade local para código escrito por agentes IA

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que torna codebases legíveis para agentes e humanos através de busca híbrida (BM25 + semântica) e observabilidade de sessões. Recupera chunks de código em milissegundos, benchmark embedders/rerankers no seu próprio repositório e rastreia o que agentes realmente fazem em sessões Claude Code.

Instalação

$npx convez-ai sivru/sivru

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
2
Acompanhando
0
Saúde
62%
Último commit
há 5 meses
Versão
v0.15.0
Issues abertas
21
Contribuidores
1

Casos de uso

  • Agentes recuperarem código relevante 78% mais rápido que ripgrep+Read
  • Diagnóstico de incidentes em codebases geradas por IA
  • Benchmark offline de embedders e rerankers em dados próprios
  • Rastreamento e auditoria de edições feitas por agentes Claude Code

Veredito

Solução honesta e técnica para o problema real de compreensão em codebases geradas por IA. Local-first, sem egress de rede, com benchmarks públicos — apropriado para times que precisam confiar e auditar agentes em produção.

README

A tradução para o português deste README ainda está na fila.

sivru

The comprehension layer for AI-written code. Local, MCP-native.

Code creation is becoming cheap. Code comprehension is becoming expensive — and as agents write more of every codebase, the gap shows up as incidents nobody can diagnose, refactors nobody dares start, and agents confidently "fixing" things that were deliberate.

Sivru keeps a codebase comprehensible — to the agents writing it and the humans accountable for it — by making comprehension a durable, queryable asset of the repo itself. The goal, the uniqueness, and the test every release must pass: GOALS.md.

Today (0.1.0) that starts with two instruments, both shipping end-to-end:

  • Search — agents call sivru via MCP and get ranked code chunks back in milliseconds instead of looping through ripgrep + Read. Hybrid BM25 + semantic + optional cross-encoder rerank. On how this squares with Anthropic's "agentic search wins for code" — WHY-SIVRU.md, the honest defense of one instrument.
  • Observe + self-benchmark — reads your Claude Code session history, shows what the agent is actually doing, and benchmarks embedders + rerankers on YOUR repos.

Next, the roadmap builds the comprehension layer proper: authored @sivru context blocks (decisions recorded with a lifetime), the sivru explain primitive, an interactive codebase explainer, and a coaching loop that catches low-context edits. See ROADMAP.md.

Status: 0.1.0. Engine, CLI, MCP server, and observe-ui ship end-to-end. See ARCHITECTURE.md for how it's built and CHANGELOG.md for what's in.


What's here

PackageWhat it does
@sivru/searchEngine. Walker → chunker → BM25 + cosine + RRF → optional cross-encoder rerank. Pluggable embedders (Model2Vec, Transformers.js, OpenAI-compatible HTTP) with asymmetric query encoding for BGE / Nomic / E5. On-disk cache + mid-session refreshStale().
sivru (CLI)search, index, from-git, mcp, observe, session, bench personal, bench models, config, doctor, explain, block, skill, checkup. Persistent embedder + reranker via sivru config.
@sivru/observeReads Claude Code's ~/.claude/projects/*.jsonl, normalizes events, runs a localhost Hono HTTP server. Ships token + dollar savings estimator and offline counterfactual replay. Also hosts the coach loop (@sivru/observe/coach) that surfaces drift in CLAUDE.md / SKILL.md / agent files. No network egress, ever — enforced by lint rule + runtime fetch spy.
@sivru/observe-uiReact + Tailwind dashboard. Tabs: Sessions / Checkup / Replay / Costs / Bench. Dark-only.
benchmarks/NDCG@10, agent-task token economy, perf gate. Raw data committed; see BENCHMARKS.md.

Numbers

Three benches. Each measures one thing. Full methodology + raw data: BENCHMARKS.md.

Token economy (sivru vs ripgrep + Read on agent tasks)

CorpusMean savedMedian savedRecall@3
Labeled (zod / requests / gson, 20 tasks)57.7% (44–70%)63.5%65% sivru vs 15% baseline
Real-world (vitest, 178k LOC, 10 tasks)78.7% (74–83%)79.9%n/a (unlabeled)

Retrieval quality (NDCG@10 on 60 labeled queries — pnpm bench)

ModeNDCG@10Cold-start (16k chunks)
BM25 + signals0.5933n/a
Hybrid · Model2Vec (default)0.6013~30 s
Hybrid · Transformers.js MiniLM0.6601~10–15 min on CPU

Benchmark sivru on your own code

Don't trust the numbers above? Run the same methodology on YOUR Claude Code sessions and YOUR repos. (Requires install — see below.)

sivru bench personal                                                # interactive picker
sivru bench personal --models bm25,potion,jina-code
sivru bench personal --models potion --rerank=ms-marco-minilm

What you get back per model:

  • Recall@5 — of the files the agent actually edited after each query in your sessions, how many appear in sivru's top 5?
  • MRR — rank of the first relevant file (1.0 = always at rank 1).
  • Tokens saved — vs. a windowed ripgrep + Read baseline.
  • Bootstrap 90% CIs on every metric so "model A beats model B" has to clear the noise floor.

Ground truth comes from the files the agent actually edited or read after each query in your jsonl session files. No labels needed — sivru derives them from the session itself.

Past runs persist to ~/.cache/sivru/bench-history/<iso>.json and render in the Bench tab of sivru observe. Full methodology, how to add custom queries, and what to do when ground truth is sparse: BENCHMARKS.md §Benchmark 3.

Install

From npm (recommended)

# Install the CLI globally:
npm install -g @sivru/cli
sivru version    # → sivru 0.1.0

# Or run without installing:
npx -y @sivru/cli help

The package on npm is @sivru/cli; the binary it installs is sivru. The rest of this README assumes the global install (or npx -y @sivru/cli for one-off invocations).

Wire into Claude Code

claude mcp add sivru -s user -- npx -y @sivru/cli mcp

Restart Claude Code. The agent now has mcp__sivru__search and mcp__sivru__find_related tools available alongside Grep / Read.

Install the routing skill

The MCP tools give the agent the capability. The skill gives it the policy — when to reach for sivru.search versus grep, and when to run find_related after an edit:

sivru skill install              # ~/.claude/skills/sivru/SKILL.md
sivru skill install --project    # or <repo>/.claude/skills/sivru/

The installed SKILL.md is the canonical routing policy — read or edit it at packages/cli/SKILL.md. sivru skill uninstall removes it.

From source (hacking on sivru)

If you want to read or modify the source, run a local build, and have Claude Code (or your shell) use that local build:

git clone https://github.com/sivru/sivru.git
cd sivru

# pnpm 9.x is required (we don't use corepack):
npm install -g pnpm@9.15.0

# Install + build all packages:
pnpm install
pnpm build

# Expose the local build as the global `sivru` command:
pnpm --filter @sivru/cli link --global

# Verify — should print the version AND show the path to YOUR local build:
sivru version
which sivru     # …/sivru/packages/cli/dist/index.js (your local path, not npm)

If sivru isn't on PATH after the link, run pnpm setup once (adds pnpm's global bin dir to your shell startup file), then open a new shell.

Claude Code with a local build

Use the linked sivru directly — don't use npx -y @sivru/cli, that would fetch from npm and bypass your local build:

claude mcp add sivru -s user -- sivru mcp

Iterating

After every change, rebuild the affected package:

pnpm --filter @sivru/cli build      # if you touched packages/cli/
pnpm build                          # if you touched any of search / observe

The global sivru command picks up the change automatically (the link points at packages/cli/dist/).

Unlink later

pnpm --filter @sivru/cli unlink --global

Search a repo

# Default = hybrid (BM25 + semantic) using the Model2Vec static embedder
# (potion-retrieval-32M). First run downloads ~129 MB to
# ~/.cache/sivru/models/ once; subsequent runs are sub-second.
sivru search "where do we sign requests" /path/to/repo
sivru search "websocket reconnect" . --top=3 --json | jq

# --bm25: skip embeddings entirely (still indexes everything via BM25).
sivru search "AuthFilter authenticate jwt" . --bm25

# Pick any catalog embedder by short name, or any HF model via hf:owner/model.
# `sivru bench models` prints the full list with size / RAM / cold-start.
sivru search "where do we sign requests" . --embed=jina-code
sivru search "where do we sign requests" . --embed=hf:Xenova/bge-small-en-v1.5

# Layer a cross-encoder reranker on top — BM25⊕embed retrieves top-50
# candidates, cross-encoder rescores them, top-K returned. Lifts
# recall@5 / NDCG@10 by 5–15% at the cost of ~100 ms / query.
sivru search "websocket reconnect" . --rerank=ms-marco-minilm
sivru search "websocket reconnect" . --rerank=bge-reranker-base   # stronger, ~5× slower

# Persist a default embedder + reranker so the MCP server picks them up.
sivru config set embedder jina-code
sivru config set reranker ms-marco-minilm

sivru index .                                              # walk + chunk + index, print stats
sivru from-git https://github.com/owner/repo               # depth=1 clone, cached + indexed
sivru bench models                                         # registered embedders + rerankers

See what your agent is doing

sivru session list                       # 20 most recent Claude Code sessions
sivru session show <id-prefix>           # event-by-event replay in the terminal

sivru observe                            # localhost web UI on http://127.0.0.1:7676

# Counterfactual analytics — zero API cost, runs on your existing sessions:
sivru observe replay <id-prefix>         # one-session "what if sivru had been here?" table
sivru observe costs --since=7            # weekly rollup: tokens used vs estimated saved
sivru observe costs --since=7 --json     # same, machine-readable

→ The web UI: sessions sidebar / event timeline / inspector pane. Estimated tokens and dollars saved per session, derived from your live Claude Code session log via the same counterfactual engine the costs CLI uses. Strictly local — no telemetry, no network egress, ever.

Pluggable embedding providers

import { buildIndex, createTransformersProvider, createHttpEmbeddingProvider } from "@sivru/search";

// Default: Xenova/all-MiniLM-L6-v2 (384-dim)
const idx = await buildIndex("./repo", { embed: { provider: createTransformersProvider() } });

// Swap to any HF model that supports the feature-extraction pipeline
createTransformersProvider({ model: "Xenova/bge-small-en-v1.5" });

// Or any OpenAI-compatible service
createHttpEmbeddingProvider({
  url: "https://api.openai.com/v1/embeddings",
  model: "text-embedding-3-small",
  dim: 1536,
  headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
});

// Or local Ollama
createHttpEmbeddingProvider({
  url: "http://localhost:11434/api/embeddings",
  model: "nomic-embed-text",
  dim: 768,
  shape: "ollama",
});

EmbeddingProvider is two methods ({ dim, embed } plus optional embedBatch) — drop in any model you can run.

Roadmap

0.1.0 ships today. v0.2 is on the milestone. Long-term direction (coaching + platform), v0.3+ themes, and what's explicitly out of scope: ROADMAP.md.

Contributing

Sivru is pre-1.0 — this is the moment to influence the surface. PRs welcome.

Got a question that isn't answered above? Open an issue with the dx_feedback label — those go to the front of the queue.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados