# code-knowledge

Drop the **Serena + CodeGraph** code-intelligence MCP layer into Claude Code — in *any* repo,
in seconds. Two local, **zero-egress** servers (no API keys, nothing leaves the machine), configured
to **auto-track `@latest`** and **auto-start** everywhere.

- **Serena** — LSP: symbols, definitions, references, rename-safe edits. Live language server, so
  it's **always fresh** (no stored index). Needs [`uv`](https://docs.astral.sh/uv) on PATH.
- **CodeGraph** — tree-sitter → SQLite call/import graph + symbol search. Returns verbatim source
  with callers + blast-radius. **Self-syncing** — a file watcher re-indexes on every save.

Self-contained: zero dependencies, plain Node ≥20, runs from any working directory.

## Two ways to install (use both)

### 1. Personal — every repo, automatically (user scope)
Registers both servers at Claude Code **user scope**, so they auto-start in *every* project you
open — no per-repo config. Run once per machine. Also adds `.codegraph/` + `.serena/` to your
**global** gitignore so no repo needs its own entry.

```bash
node code-knowledge.js global
```

### 2. Team-shareable — per repo (checked-in `.mcp.json`)
Run inside a repo. Writes/merges `.mcp.json` (preserving any other servers), gitignores the index
dirs, pre-builds the CodeGraph index, and appends a short "query these before grep" note to
`CLAUDE.md`. Commit `.mcp.json` + `CLAUDE.md` and your teammates inherit it on clone.

```bash
cd /path/to/other-repo
node /path/to/code-knowledge.js repo          # flags: --no-index, --no-claude-md
```

### Both at once
```bash
node code-knowledge.js both
```

### Check your environment
```bash
node code-knowledge.js doctor
```

> After any install: **RESTART Claude Code**, then run `/mcp`. MCP servers attach on restart, not
> mid-session. Project scope (`.mcp.json`) also prompts once to trust the repo's servers; user scope
> is trusted once.

## Reuse it from anywhere

Published at **https://github.com/bhanutejaI4E/code-knowledge** — run from any repo, no clone:

```bash
npx -y github:bhanutejaI4E/code-knowledge doctor   # check environment
npx -y github:bhanutejaI4E/code-knowledge repo     # set up the current repo
npx -y github:bhanutejaI4E/code-knowledge global   # user scope (once per machine)
```

Or **copy** this folder next to your projects and call it by path (examples above).
Forking it? Swap the handle for your own GitHub username.

## The `@latest` policy (and its cost)

Both servers deliberately track the newest release:

- **CodeGraph** → `@colbymchenry/codegraph@latest` — npx re-checks npm on each start.
- **Serena** → `uvx --refresh …` — uvx re-resolves the git source on each start.

Trade-off: each launch does a quick upstream check (a little startup latency + needs network), and
an occasional CodeGraph version bump may want a fresh `init` if its index schema changes. If a bad
release ever lands, pin a server to an exact version in [lib/servers.js](lib/servers.js) (e.g.
`@colbymchenry/codegraph@1.1.6`, or a Serena git tag) and re-run the installer.

## Files

| File | Role |
|------|------|
| [code-knowledge.js](code-knowledge.js) | CLI entry / command dispatch |
| [lib/servers.js](lib/servers.js) | **Single source of truth** for both server definitions |
| [lib/commands/global.js](lib/commands/global.js) | User-scope registration + global gitignore |
| [lib/commands/repo.js](lib/commands/repo.js) | Per-repo `.mcp.json` / gitignore / index / CLAUDE.md |
| [lib/commands/doctor.js](lib/commands/doctor.js) | Prerequisite + registration report |
| [lib/prereqs.js](lib/prereqs.js), [lib/util.js](lib/util.js) | Shared helpers |
| [templates/claude-snippet.md](templates/claude-snippet.md) | The CLAUDE.md guidance block |