hald

Your codebase, held.

From the Old Norse hald — a hold, a keeping.

GraphRAG-powered codebase intelligence. Builds a knowledge graph from your git history — commits, authors, files, relationships — and lets you query it with natural language. Like having a senior engineer who's read every commit and can answer any question about your codebase instantly.

Run hald scan once. Then hald graph opens an interactive view of your codebase as a knowledge graph — communities labeled with LLM-generated summaries, top experts highlighted, click any cluster to explain it.

Quick Start

# Install (requires Node.js 20+)
npm install -g haldy

# Try it now — zero key, zero cost: open a built-in demo graph
hald graph --mock

# Scan your repository (uses an LLM API key if one is set;
# falls back to a key-free, agent-mediated path otherwise)
cd your-repo
hald scan

# Ask questions
hald ask "who knows the billing module best?"
hald ask "why did we migrate to gRPC?"
hald ask "what changed most in the last 3 months?"
hald stats

No API key? hald scan falls back to agent-mediated extraction — your AI agent performs the entity extraction itself at zero extra cost (see LLM Providers).

How It Works

git log
   |
   v
 Chunker          (commits -> overlapping text units)
   |
   v
LLM Extraction    (entities: people, modules, decisions, patterns)
   |
   v
Entity Resolver   (deduplication + canonical names)
   |
   v
Knowledge Graph   (nodes + weighted edges in SQLite)
   |
   v
Community Detection  (Louvain clustering + LLM summaries)
   |
   v
MCP Tools         (hald_find_expert, hald_trace_decision, ...)
   |
   v
Your AI Agent     (synthesizes answers using its own tokens)

Scanning costs tokens. Querying is always free — tools return structured graph data and your agent does the reasoning.

Visual Explorer

hald graph                # open the real index (default)
hald graph --mock         # open a built-in fixture graph for design iteration

Opens an interactive visualization in your browser. Built-in:

• Atmospheric canvas — subtle radial gradient gives clusters depth. Solid fallback for browsers without radial-gradient.
• Communities labeled with LLM summaries — each cluster's title floats above the topmost node in the cluster (not at the centroid, so it never sits on a node). Hover for the full summary, click to open a detail card with the top 5 entities.
• Top experts surfaced by default — the most-connected nodes are labeled on first paint so you have anchors immediately.
• Weight-mapped edges — thickness AND alpha scale with relation weight (log-mapped). Heavy connections feel heavy; cross-cluster bridges stay quiet. Edges render as quadratic Bezier curves on a 2D overlay below the WebGL canvas.
• Focus halo on hover — the active node gets a soft amber-to-community-color glow. Resting state stays clean (no donut overlap).
• Breathing motion — nodes drift gently around their layout positions via uncorrelated sine oscillators. Honors prefers-reduced-motion: reduce.
• Hover ripple — neighbors of the hovered node briefly pulse so the local neighborhood reads at a glance.
• Cmd-click paths — ⌘-click (mac) or Ctrl-click (linux/win) a second node while one is selected to trace the shortest path. The path lights up in amber with a floating banner showing the full hop list AND the relation type between each pair (Alice ─authored→ src/extractor ─uses→ src/store). Click any hop to navigate without losing the path. Esc / ✕ / click-empty-space to clear.
• Zoom-driven label density — zoom in past ~0.4× to see labels on everything, zoom out past 2× to drop down to community labels only.
• Search and filter — / focuses search, type chips toggle entity types on/off, Esc closes panels. "0 matches" shows inline at the top of the canvas.
• Light + dark mode — follows system preference, toggleable in the header. Hover label pill recolors per theme so it stays readable.
• Shareable URLs — selected node and active filters persist in the URL hash. Copy/paste to send a specific view.
• PNG export — one click to save the current view as an image. Captures the curved edge overlay and the live community labels.
• Keyboard nav — arrow keys pan, / searches, Esc closes / clears path / closes sidebar.
• Mock mode — hald graph --mock boots a hand-curated fixture graph (~50 entities, 6 communities) for visual iteration without re-indexing or any LLM cost.

Works fully offline — no CDN dependencies.

What You Can Ask

LLM Providers

hald auto-detects your available API key. Set one of these before running hald scan for the fastest, highest-quality indexing. No key set? hald falls back to agent-mediated extraction — your AI agent does the extraction itself at zero extra cost.

Querying is always free — no LLM calls at query time.

Platform Setup

Claude Code

Add hald to your project's .mcp.json:

{
  "mcpServers": {
    "hald": {
      "command": "npx",
      "args": ["haldy", "serve"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "hald": {
      "command": "npx",
      "args": ["haldy", "serve"],
      "env": {
        "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Codex

See .codex/INSTALL.md for setup instructions.

OpenCode

Copy .opencode/plugins/hald.js to your OpenCode plugins directory.

Gemini CLI

Install directly from the repo:

gemini extensions install https://github.com/gabrielcarvvlho/hald

Or install from a local checkout (Gemini extensions are directories, not single files):

mkdir -p ~/.gemini/extensions/hald && cp gemini-extension.json ~/.gemini/extensions/hald/

CLI Reference

hald scan [options]            Build or update the knowledge graph
  --full                       Force full re-scan (ignore existing index)
  --max-commits <n>            Limit number of commits to process
  --since <date>               Only scan commits after this date (YYYY-MM-DD)
  --provider <name>            LLM provider: anthropic | openai | google | zhipu | auto
  -y, --yes                    Skip cost confirmation prompt

hald ask <question>            Ask a natural language question
  --type <type>                Search strategy: local | global | auto

hald stats                     Show index statistics

hald graph                     Open interactive graph visualization in browser
  --mock                         Use a built-in fixture graph (no index required)
  --port <number>                HTTP server port (default 3742)
  --no-open                      Don't auto-open the browser

hald reset                     Delete the local index and start fresh

hald serve                     Start the MCP server on stdio

Configuration

Configuration priority (first wins):

1. CLI flags / MCP tool parameters
2. .hald/config.json in repo root
3. Environment variables (HALD_*)
4. Defaults

Storage

Index lives in .hald/ at the repo root. Add to .gitignore:

.hald/

Safe to delete — run hald scan again to rebuild.

Development

git clone https://github.com/gabrielcarvvlho/hald.git
cd hald
npm install
npm run build
npm test

See CONTRIBUTING.md for guidelines.

License

MIT