{
  "markdown": "# hald\n\n**Your codebase, held.**\n\n<sub>*From the Old Norse **hald** — a hold, a keeping.*</sub>\n\nGraphRAG-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.\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/haldy\"><img src=\"https://img.shields.io/npm/v/haldy?style=flat-square\" alt=\"npm version\"></a>\n  <a href=\"https://github.com/gabrielcarvvlho/hald/actions\"><img src=\"https://img.shields.io/github/actions/workflow/status/gabrielcarvvlho/hald/ci.yml?style=flat-square\" alt=\"CI\"></a>\n  <a href=\"https://github.com/gabrielcarvvlho/hald/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-blue?style=flat-square\" alt=\"MIT License\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"docs/assets/hero.gif\">\n    <img src=\"docs/assets/hero.gif\" alt=\"Hald viz: communities, summaries, click-to-explain\" width=\"820\">\n  </a>\n</p>\n\n> 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.\n\n## Quick Start\n\n```bash\n# Install (requires Node.js 20+)\nnpm install -g haldy\n\n# Try it now — zero key, zero cost: open a built-in demo graph\nhald graph --mock\n\n# Scan your repository (uses an LLM API key if one is set;\n# falls back to a key-free, agent-mediated path otherwise)\ncd your-repo\nhald scan\n\n# Ask questions\nhald ask \"who knows the billing module best?\"\nhald ask \"why did we migrate to gRPC?\"\nhald ask \"what changed most in the last 3 months?\"\nhald stats\n```\n\nNo API key? `hald scan` falls back to **agent-mediated extraction** — your AI agent\nperforms the entity extraction itself at zero extra cost (see [LLM Providers](#llm-providers)).\n\n## How It Works\n\n```\ngit log\n   |\n   v\n Chunker          (commits -> overlapping text units)\n   |\n   v\nLLM Extraction    (entities: people, modules, decisions, patterns)\n   |\n   v\nEntity Resolver   (deduplication + canonical names)\n   |\n   v\nKnowledge Graph   (nodes + weighted edges in SQLite)\n   |\n   v\nCommunity Detection  (Louvain clustering + LLM summaries)\n   |\n   v\nMCP Tools         (hald_find_expert, hald_trace_decision, ...)\n   |\n   v\nYour AI Agent     (synthesizes answers using its own tokens)\n```\n\nScanning costs tokens. Querying is always free — tools return structured graph data and your agent does the reasoning.\n\n## Visual Explorer\n\n```bash\nhald graph                # open the real index (default)\nhald graph --mock         # open a built-in fixture graph for design iteration\n```\n\nOpens an interactive visualization in your browser. Built-in:\n\n- **Atmospheric canvas** — subtle radial gradient gives clusters depth. Solid fallback for browsers without `radial-gradient`.\n- **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.\n- **Top experts surfaced by default** — the most-connected nodes are labeled on first paint so you have anchors immediately.\n- **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.\n- **Focus halo on hover** — the active node gets a soft amber-to-community-color glow. Resting state stays clean (no donut overlap).\n- **Breathing motion** — nodes drift gently around their layout positions via uncorrelated sine oscillators. Honors `prefers-reduced-motion: reduce`.\n- **Hover ripple** — neighbors of the hovered node briefly pulse so the local neighborhood reads at a glance.\n- **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.\n- **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.\n- **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.\n- **Light + dark mode** — follows system preference, toggleable in the header. Hover label pill recolors per theme so it stays readable.\n- **Shareable URLs** — selected node and active filters persist in the URL hash. Copy/paste to send a specific view.\n- **PNG export** — one click to save the current view as an image. Captures the curved edge overlay and the live community labels.\n- **Keyboard nav** — arrow keys pan, `/` searches, `Esc` closes / clears path / closes sidebar.\n- **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.\n\nWorks fully offline — no CDN dependencies.\n\n## What You Can Ask\n\n| Question type | Example | Tool used |\n|---|---|---|\n| Ownership | \"Who knows the payments module best?\" | `hald_find_expert` |\n| Decisions | \"Why did we switch from REST to gRPC?\" | `hald_trace_decision` |\n| Coupling | \"What breaks when I touch the auth layer?\" | `hald_show_coupling` |\n| Silos | \"Are there parts of the codebase nobody touches?\" | `hald_find_silos` |\n| Relationships | \"How are the queue system and billing connected?\" | `hald_get_path` |\n| Free-form | \"Summarize the architecture of the data pipeline\" | `hald_query` |\n\n## LLM Providers\n\nhald 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.\n\n| Provider | Env Var | Default Model | Cost per 1k commits |\n|---|---|---|---|\n| Anthropic | `ANTHROPIC_API_KEY` | claude-sonnet-4-6 | ~$0.50-$1.00 |\n| OpenAI | `OPENAI_API_KEY` | gpt-5.4-mini | ~$0.50-$1.00 |\n| Google | `GOOGLE_API_KEY` | gemini-3.1-flash-lite-preview | ~$0.15-$0.40 |\n| Zhipu AI | `ZHIPU_API_KEY` | glm-4-flash | ~$0.05-$0.15 |\n| Ollama (local) | `OPENAI_API_KEY` + `HALD_BASE_URL` | configurable | $0.00 |\n\nQuerying is always free — no LLM calls at query time.\n\n## Platform Setup\n\n### Claude Code\n\nAdd hald to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"hald\": {\n      \"command\": \"npx\",\n      \"args\": [\"haldy\", \"serve\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"hald\": {\n      \"command\": \"npx\",\n      \"args\": [\"haldy\", \"serve\"],\n      \"env\": {\n        \"ANTHROPIC_API_KEY\": \"${env:ANTHROPIC_API_KEY}\"\n      }\n    }\n  }\n}\n```\n\n### Codex\n\nSee [`.codex/INSTALL.md`](.codex/INSTALL.md) for setup instructions.\n\n### OpenCode\n\nCopy `.opencode/plugins/hald.js` to your OpenCode plugins directory.\n\n### Gemini CLI\n\nInstall directly from the repo:\n\n```bash\ngemini extensions install https://github.com/gabrielcarvvlho/hald\n```\n\nOr install from a local checkout (Gemini extensions are directories, not single files):\n\n```bash\nmkdir -p ~/.gemini/extensions/hald && cp gemini-extension.json ~/.gemini/extensions/hald/\n```\n\n## CLI Reference\n\n```\nhald scan [options]            Build or update the knowledge graph\n  --full                       Force full re-scan (ignore existing index)\n  --max-commits <n>            Limit number of commits to process\n  --since <date>               Only scan commits after this date (YYYY-MM-DD)\n  --provider <name>            LLM provider: anthropic | openai | google | zhipu | auto\n  -y, --yes                    Skip cost confirmation prompt\n\nhald ask <question>            Ask a natural language question\n  --type <type>                Search strategy: local | global | auto\n\nhald stats                     Show index statistics\n\nhald graph                     Open interactive graph visualization in browser\n  --mock                         Use a built-in fixture graph (no index required)\n  --port <number>                HTTP server port (default 3742)\n  --no-open                      Don't auto-open the browser\n\nhald reset                     Delete the local index and start fresh\n\nhald serve                     Start the MCP server on stdio\n```\n\n## Configuration\n\nConfiguration priority (first wins):\n\n1. CLI flags / MCP tool parameters\n2. `.hald/config.json` in repo root\n3. Environment variables (`HALD_*`)\n4. Defaults\n\n| Env Var | Description | Default |\n|---|---|---|\n| `HALD_PROVIDER` | LLM provider for scanning | `auto` |\n| `HALD_MODEL` | Override default model | provider default |\n| `HALD_BASE_URL` | Custom endpoint (Ollama, OpenRouter, Azure) | -- |\n| `HALD_MAX_COMMITS` | Max commits to scan | unlimited |\n\n## Storage\n\nIndex lives in `.hald/` at the repo root. Add to `.gitignore`:\n\n```\n.hald/\n```\n\nSafe to delete — run `hald scan` again to rebuild.\n\n## Development\n\n```bash\ngit clone https://github.com/gabrielcarvvlho/hald.git\ncd hald\nnpm install\nnpm run build\nnpm test\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT\n",
  "bytes": 9428,
  "sha": "142942a58043164e7d1a96d0a8b90ec4e6101b22ef9f3307034c4fe59728e662",
  "repo_slug": "gabrielcarvvlho/hald",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_gabrielcarvvlho_hald_63be110d/readme"
}