Local-first codebase intelligence.

Chat, search, and audit any repository - every answer cited [source: file:line].
Works inside Cursor, Claude, Windsurf, VS Code, Zed and any MCP client - or standalone in your terminal.

Website · MCP docs · Roadmap · Changelog · Contributing

Get started

npx codebase-chat-mcp setup

One command. The wizard detects Cursor, Claude, Windsurf, VS Code, Zed, Gemini CLI, Kiro, Cline and Roo Code, asks how you want answers (host model or API key), writes the config - done. No JSON to edit, no API key required.

Real MCP session on a real 422-file codebase - codebase_health finds 324 circular deps, codebase_chat answers with [source: file:line] receipts · PR review (--diff + --watch) · CLI tour · MCP stdio · French mode

One engine, three surfaces

In your IDE	In your terminal	Fully offline
21 MCP tools inside Cursor, Claude, Windsurf & more - answers land where you code	npx codebase-chat - index, search, health, check. Drop --check --strict into CI	--no-llm deterministic reports + --ui dashboard - no model, no key, no cloud

Every claim comes with a citation. Every metric is computed from your code. Your repo is never uploaded - the model only sees the excerpts that matter.

Understand	Verify	Act
chat · search · explain · intelligence	health · impact · check vs baseline · deep_audit (30 metrics)	refactor · tasks · fix · apply - dry-run, backups, protected paths

Local dashboard - --ui

npx codebase-chat --ui    # → http://127.0.0.1:<port> - nothing leaves your machine

The audit as a real app - dense IDE-style UI, not a webpage:

• Command palette Ctrl+K - jump between views, build a prompt, export, toggle zen mode
• Zen mode z · view shortcuts 1–5 · / filters findings by text or severity
• Diff vs baseline, ignore findings with a justification, export .md / .html - all in clicks
• Bilingual FR / EN

Real output

What a session actually returns - run on this repository:

$ npx codebase-chat --health

== STATIC ANALYSIS - codebase-chat ==
Health score: 52/100 (D) · 33 files analyzed · 65 local imports

● Circular dependencies (0)
  none

● Unused files (candidates) (1)
  lib/client.js

● Complexity hotspots (13)
  lib/index.js - score 418
  src/analysis.ts - score 81
  …

$ npx codebase-chat --search "health score computation"

--- src/analysis.ts :: formatHealthReportMd (FUNCTION) [source: src/analysis.ts:285-353] ---
--- src/analysis.ts :: analyzeProject       (FUNCTION) [source: src/analysis.ts:149-232] ---
--- src/analysis.ts :: HealthReport         (TYPE)     [source: src/analysis.ts:15-26]   ---

$ npx codebase-chat --ask "how is the index cached?"

> codebase-chat · prompt-only mode (no API key)
> Chunks: 81 · Tokens: 59,934 → handed to the host model
> Cite every technical claim with [source: relative/path:line].

codebase_health runs fully offline - deterministic, no LLM, same input → same score. Every answer from codebase_chat arrives with receipts you can verify in seconds.

Verify your changes

$ npx codebase-chat --baseline        # snapshot findings + score to .codebase-chat/baseline.json (commit it)
$ npx codebase-chat --check           # impact + findings on files changed vs HEAD, diffed vs baseline
$ npx codebase-chat --check --strict  # exit 1 on a red verdict - drop into CI
$ npx codebase-chat --doctor          # diagnose the install: node, index cache, keys, MCP clients

From an IDE: codebase_check / codebase_doctor MCP tools, or /codebase check in DeepSeek Harness.

Why it wins

	Paste into a chat	Hosted assistant	codebase-chat
Sees your whole repo, not one file	❌	✅	✅
[source: file:line] citations	❌	~	✅
Repo never uploaded - model sees only relevant excerpts	❌	❌	✅
Inside Claude / Cursor / Windsurf	❌	~	✅
Fully offline - --no-llm report & --ui dashboard, zero model	❌	❌	✅
Free - no API key, no account	~	❌	✅

How it works

Writes are safe by construction - dry-run · .dsh-backups/ before overwrite · protected paths · never outside the project.

Ten tools run fully deterministic - no model, no key, works offline: health, impact, check, doctor, ignore, fix, stats, history, baseline, deep_audit (9 sections, ~30 metrics: git churn, bus factor, secrets, deps, per-function complexity).

Reference

Install - all paths

MCP server - manual config

{
  "mcpServers": {
    "codebase-chat": {
      "command": "npx",
      "args": ["codebase-chat-mcp"]
    }
  }
}

Without DEEPSEEK_API_KEY / OPENAI_API_KEY the server runs promptOnly. Set either key for direct-LLM calls - see mcp/README.md.

CLI

npx codebase-chat --project C:\my-app --ask "how is auth handled?"
npx codebase-chat --project C:\my-app --health   # offline, no LLM
npx codebase-chat --project C:\my-app --health --diff main   # only what changed
npx codebase-chat --project C:\my-app --watch    # index stays hot while you code
npx codebase-chat --project C:\my-app --prompt intelligence   # same brief the IDE gets - pipe to any LLM
npx codebase-chat --project C:\my-app --prompt intelligence --call    # DeepSeek/OpenAI answers directly (API key)
npx codebase-chat --project C:\my-app --prompt intelligence --no-llm  # deterministic report - zero model, zero key
npx codebase-chat --project C:\my-app --ui   # interactive HTML dashboard on localhost - no LLM

DeepSeek Harness plugin

dsh plugin --profile web add codebase-chat

Then restart dsh web → http://127.0.0.1:3080 → Codebase Pro button.

From source

git clone https://github.com/shinzarou-eng/codebase-chat.git
cd codebase-chat && pnpm install && pnpm build

Slash commands (DeepSeek Harness)

dsh --profile headless '/codebase "how is auth handled?" --project C:\my-app'
dsh --profile headless '/codebase-search "usePetStore" --project C:\my-app'
dsh --profile headless '/codebase-explain "storage.ts" --project C:\my-app'
dsh --profile headless '/codebase-refactor "split this hook" --file storage.ts --project C:\my-app'
dsh --profile headless '/codebase-intel --project C:\my-app'
dsh --profile headless '/codebase-audit --project C:\my-app --lang en'
dsh --profile headless '/codebase-tasks --project C:\my-app'
dsh --profile headless '/codebase-apply-tasks --project C:\my-app'
dsh --profile headless '/codebase-build --project C:\my-app'
dsh --profile headless '/codebase-git --project C:\my-app'

.codebase-chat.json - per-project settings

{
  "lang": "en",
  "maxTokens": 60000,
  "ignoreDirs": ["generated", "fixtures"],
  "ignoreFiles": ["bundle.js"],
  "ignoreGlobs": ["src/vendor/**", "*.snap"],
  "protectedPaths": ["src/locked", "migrations"]
}

Key	Effect
lang	Default prompt language (en/fr) - CLI, MCP tools, slash commands
maxTokens	Context budget when the caller passes none
ignoreDirs / ignoreFiles	Extra names skipped by indexing, codebase_health, file tree
ignoreGlobs	Globs on project-relative paths - ** spans dirs, * one segment
protectedPaths	Paths the apply pipeline can never patch

Environment variables

Variable	Default	Purpose
CODEBASE_CACHE_DIR	OS cache dir	Where the index cache lives
DSH_PROJECT_ALIASES	-	Extra name=path aliases (;-separated)
DSH_PROTECTED_PATHS	built-in list	Extra paths that can never be patched
DEEPSEEK_API_KEY / OPENAI_API_KEY	-	Direct-LLM mode only
DEEPSEEK_BASE_URL / OPENAI_BASE_URL	https://api.deepseek.com/v1	Custom endpoint
CODEBASE_MODEL	deepseek-chat	Model for direct-LLM mode

Plain words - 🇫🇷 inside

Point it at a folder of code. Ask questions like a human - "How does login work?", "What should I fix first?" - in French or English. Every answer cites the exact file and line it came from. Nothing is uploaded anywhere.

Pointez-le vers un dossier de code. Posez vos questions en langage clair. Chaque réponse cite le fichier et la ligne exacts. Rien n'est envoyé sur internet.

Term	Meaning
MCP server	A plug format that lets AI assistants use extra tools. Install once - your IDE can "see" your code.
Prompt-only	The tool prepares the context; your existing AI writes the answer. No extra key, no extra cost.
Deterministic	Computed directly from your code - same input, same result, every time.

Project layout & dev

├── lib/            DeepSeek Harness plugin (index.js) + Codebase Pro UI (client.js)
├── src/            TypeScript engine - indexer, extractor, retriever, tokenizer, context, CLI
├── mcp/            Standalone MCP server package (codebase-chat-mcp)
├── test/           Vitest suites (extractor, retriever, tasks pipeline)
├── docs/           Landing page (GitHub Pages) + assets
└── dist/           Build output (tsup)

pnpm install && pnpm build && pnpm test && pnpm typecheck

FAQ

Does it send my code to the cloud? Indexing, retrieval, and prompt building all run on your machine. In prompt-only mode the server makes no network calls itself - the assembled context is read by your host model (cloud or local, your choice). For zero-network output end to end, use --no-llm: a deterministic report computed from your code only.

Do I need an API key? No - three ways to get output: the host model (promptOnly, best quality - pipe it to a local model like Ollama for offline answers), a DeepSeek/OpenAI key (--call), or the deterministic report (--no-llm, no model at all). Inside DeepSeek Harness, the plugin uses your configured model.

Which languages are supported? French and English via lang on every tool. Source-side, AST covers JS/TS, Python, Go, Rust, Java, C#, PHP - the rest is indexed line by line.

Is applying patches safe? Yes. Dry-run, backups before overwrite, protected paths, writes stay inside the project.

EADDRINUSE on port 3080?

Get-NetTCPConnection -LocalPort 3080 | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }

Then restart dsh --profile web.

Roadmap

Shipped	tree-sitter AST (7 languages), deterministic health score + --no-llm deep audit, --ui local dashboard (IDE-style, Ctrl+K palette, zen mode, bilingual, exports), check/fix/ignore/doctor verified workflow + baseline & CI gate, deep_audit MCP tool + ui:// resource, token/context stats, MCP setup wizard, .codebase-chat.json, --diff scoping, --watch mode
Next	GitHub Issues export from TASKS.md, prompt language packs (ES/DE/PT)
Planned	VS Code extension, HTTP/SSE transport, PR review mode
Exploring	multi-repo workspaces, shared team index cache, CI bot

_{Full detail: ROADMAP.md}

---

If this project helps you - star it on GitHub ⭐

Website · Issues · Support · Security

_{MIT License - built and maintained by shinzarou-eng}