Content
# hyphae
> Code intelligence for Claude Code — your codebase as a self-learning knowledge graph.
Hyphae indexes your repos and wires three tools directly into Claude Code's context: semantic symbol search, deep structural context, and blast-radius analysis for refactors. The graph learns from how you use it, improving confidence scores over time.
**Languages:** TypeScript · JavaScript · Python · Go · Rust
---
## Why "hyphae"?
In nature, hyphae are the thread-like filaments that form the mycelium of a fungus — a vast, invisible network that spreads through soil, connects trees and plants, and transfers nutrients and signals across an entire ecosystem. The mycelium doesn't just link things; it learns which pathways matter and strengthens them over time.
This project works the same way. It spreads through your codebase, maps every symbol and relationship into a living knowledge graph, and quietly transfers that context to Claude whenever you need it. The more you use it, the more it learns — strengthening edges that lead to real answers and fading out noise.
Like mycelium: invisible infrastructure, working beneath the surface, making the whole ecosystem smarter.
---
## Install
```bash
npm install -g hyphae-intel
hyphae setup ~/projects # register MCP + index every git repo under ~/projects
```
Restart Claude Code. That's it — hyphae is active in every session.
---
## What you can ask Claude once it's running
Hyphae adds three tools to Claude's context. You don't invoke them directly — Claude uses them automatically when answering your questions.
### Find anything
> *"Where is authentication handled?"*
> *"Find the rate limiter"*
> *"Show me everything related to payment processing"*
The **query** tool searches by meaning, not just name. It embeds your question and matches it against every symbol in the graph using cosine similarity, falling back to name-based search when needed.
### Understand a symbol completely
> *"How does UserService work? What calls it, what does it call, what does it extend?"*
> *"Show me the full context for the Indexer class"*
The **context** tool returns every incoming and outgoing edge for a symbol — callers, callees, imports, inheritance, interface implementations — grouped by relationship type.
```
UserService
← IMPORTS : AuthProvider, DatabasePool
← CALLS : UserService (from AuthMiddleware, UserController ×3)
→ CALLS : DatabasePool.query, Logger.info, CacheService.get
→ EXTENDS : BaseService
→ IMPLEMENTS: IUserService
```
### Know what breaks before you touch it
> *"If I change the signature of parseConfig, what else will break?"*
> *"What's the blast radius of renaming DatabasePool?"*
> *"Show me everything upstream of the payment webhook handler"*
The **impact** tool traverses the graph to find all transitive dependents, grouped by depth. A confidence threshold filters out weak or speculative edges so you only see real risk.
```
DatabasePool → downstream impact (depth 3)
depth 1: UserService, AuthService, CacheService
depth 2: UserController, AuthMiddleware, SessionHandler
depth 3: ApiRouter, WebhookHandler
risk: HIGH (23 downstream symbols)
```
---
## Multi-repo support
Index all your repos and Claude can reason across them simultaneously. The `repo` parameter on every tool lets you target a specific one by name:
```
hyphae index --all ~/projects # index everything under ~/projects
hyphae index --cross-repo . # resolve edges that reference other repos
```
Claude automatically uses the most recently indexed repo when no `repo` param is specified. When you have multiple, it can compare patterns across them.
---
## Dashboard
```bash
hyphae ui
```
Opens a local dashboard at `http://localhost:4242` with:
- **Knowledge graph** — interactive force-directed view of your codebase, nodes coloured by kind (Class, Function, Interface…), edges weighted by confidence
- **Tool call activity** — bar chart of Claude's queries over the last 14 days
- **Outcome distribution** — how many tool calls resolved as success vs unknown
- **Node kind breakdown** — horizontal bar chart of symbol composition
- **Repo overview** — node/edge counts and last indexed time per repo
The dashboard reads directly from your local indexes — no data leaves your machine.
---
## Keep indexes fresh
**Manual** — run after significant changes:
```bash
hyphae index # incremental (only changed files)
hyphae index --force # full reindex
```
**Automatic** — install a post-commit hook:
```bash
hyphae setup --git-hook
```
The incremental indexer uses content hashes (not timestamps) to detect changes, so it only re-parses files that actually changed.
---
## The confidence model
Every edge in the graph carries a multi-dimensional confidence score:
| Dimension | Source | Weight |
|-----------|--------|--------|
| `static` | Type-aware resolution (ts-morph, tree-sitter) | 1.0 |
| `heuristic` | Framework conventions, decorator patterns, cross-file analysis | 0.8 |
| `learned` | Observed tool usage over ≥50 events | 1.0 |
| `runtime` | Imported execution traces | 1.2 |
| `aggregate` | Weighted combination | — |
`null` means no evidence yet — not penalised. As you use Claude to explore the codebase, the `learned` dimension updates based on which symbols actually get acted on after a query.
---
## CLI reference
```
hyphae setup [dir] Register MCP + index all git repos in a directory
hyphae setup --mcp-only Only register MCP, skip indexing
hyphae setup --git-hook Install post-commit reindex hook in current repo
hyphae index [path] Incremental index (default: current directory)
hyphae index --force [path] Full reindex, ignoring content hashes
hyphae index --all <dir> Index all git repos under a directory
hyphae index --cross-repo [path] Resolve cross-repo edges after indexing
hyphae index --watch [path] Watch for file changes and reindex automatically
hyphae status [path] Show node/edge counts and last indexed time
hyphae query <text> Search the graph from the terminal
hyphae context <symbol> Show structural context for a symbol
hyphae impact <symbol> Show blast radius (upstream by default)
hyphae impact -d both <symbol> Upstream + downstream
hyphae impact --depth 5 <symbol> Deeper traversal
hyphae ui Open the local dashboard (graph + learning charts)
hyphae ui 8080 Use a custom port (default: 4242)
hyphae doctor Check MCP registration, index health, model cache
hyphae log Show recent tool-call and indexing events
hyphae trace Import runtime trace data to update confidence
hyphae clean Delete the index for the current repo
hyphae clean --all --force Delete all indexes
hyphae serve Start the MCP server (Claude Code runs this automatically)
```
---
## Configuration
Hyphae works with zero config. To customise, add `.hyphae.json` to the repo root:
```json
{
"ignore": ["node_modules", "dist", "build", ".next", "vendor"],
"embeddings": {
"enabled": true,
"model": "Xenova/all-MiniLM-L6-v2"
}
}
```
Disable embeddings on a large repo to speed up initial indexing — you can re-enable later and reindex with `--force`.
---
## How it works
```
hyphae index
│
├─ walk discover files, compute content hashes
├─ parse tree-sitter structural extraction (nodes + DEFINES edges)
├─ resolve ts-morph type-aware pass (CALLS, IMPORTS, EXTENDS, IMPLEMENTS)
├─ score heuristic rules, cross-file analysis, learned confidence
└─ embed all-MiniLM-L6-v2 embeddings per node
│
.hyphae/graph.db (SQLite, WAL mode)
│
Claude Code ◄── MCP stdio ◄── query / context / impact
```
The index lives in `.hyphae/graph.db` inside each repo (gitignored). A global registry at `~/.hyphae/registry.json` tracks all indexed repos — `hyphae serve` loads them all at startup so Claude has access to everything.
---
## From source
```bash
git clone https://github.com/dgtise25/hyphae
cd hyphae && npm install && npm run build && npm link
hyphae setup ~/projects
```
---
## License
MIT
