shinzarou-eng/dsh-codebase-chat

Website · MCP docs · Roadmap · Changelog · Contributing

Get started

npx dsh-codebase-chat-mcp setup

The wizard detects Claude, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Kiro, Cline and Roo Code, asks how you want answers (host model, API key, or offline local model), writes the MCP config, done. No JSON to edit — and no API key: in promptOnly mode your host model does the thinking, or go fully offline with the embedded local model (localLlm) — no key, no host, no cloud.

Other paths — DeepSeek Harness plugin · CLI · from source · manual config: Reference.

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

What a real session looks like

Run on this repository — the exact text the tools return:

$ npx dsh-codebase-chat --project . --health

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

● Circular dependencies (0)
  none

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

● Unused exports (candidates) (45)
  lib/cache.js:21 — cachePath
  lib/index.js:2952 — normalizeLabels
  lib/index.js:2952 — getProjectName
  …

● Duplicate code blocks (2)
  12 lines × 2 files — lib/index.js, src/project.ts
  6 lines × 2 files — src/indexer.ts, src/retriever.ts

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

$ npx dsh-codebase-chat --project . --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 dsh-codebase-chat --project . --ask "how is the index cached?"

> dsh-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 [source: file:line] receipts you can verify in seconds.

Why it wins

	Paste into a chat	Hosted assistant	dsh-codebase-chat
Sees your whole repo, not one file	❌	✅	✅
[source: file:line] citations	❌	~	✅
Code stays on your machine	❌	❌	✅
Inside Claude / Cursor / Windsurf	❌	~	✅
Deterministic health score, no LLM	❌	❌	✅
Answers fully offline (embedded LLM)	❌	❌	✅
Free — no API key, no account	~	❌	✅

How it works

/codebase-apply writes safely — dry-run · .dsh-backups/ before overwrite · protected paths · never outside the project.

The 13 tools

Understand	Decide	Act	Explore
codebase_chat	codebase_intelligence	codebase_refactor	codebase_player
codebase_search	codebase_audit	codebase_tasks	codebase_crea
codebase_explain	codebase_report
codebase_health	codebase_ceo
codebase_impact

Same engine, three surfaces: MCP tools in your IDE, slash commands in DeepSeek Harness, CLI flags anywhere. Every tool takes lang (fr/en), embed, promptOnly, localLlm, maxTokens.

Reference

Install — all paths

DeepSeek Harness plugin

dsh plugin --profile web add dsh-codebase-chat

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

CLI

npx dsh-codebase-chat --project C:\my-app --ask "how is auth handled?"
npx dsh-codebase-chat --project C:\my-app --health   # offline, no LLM
npx dsh-codebase-chat --project C:\my-app --health --diff main   # only what changed
npx dsh-codebase-chat --project C:\my-app --watch    # index stays hot while you code
npx dsh-codebase-chat --project C:\my-app --prompt intelligence   # same banner brief the IDE gets — pipe to any LLM

From source

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

Manual MCP config

{
  "mcpServers": {
    "dsh-codebase-chat": {
      "command": "npx",
      "args": ["dsh-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.

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_DAKO_PROJECT	—	Override the built-in dako alias
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
CODEBASE_LOCAL_LLM	—	1 enables the embedded local model (offline answers); hf:owner/repo:QUANT or a .gguf path picks another model

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 (dsh-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 answers end to end, enable the embedded local model (localLlm).

Do I need an API key? No — three ways to get answers: the host model (promptOnly, best quality), a DeepSeek/OpenAI key, or the embedded local model (localLlm, fully offline). The local model is small — great for quick lookups, prefer a hosted model for full reports. 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, MCP setup wizard, .codebase-chat.json, --diff scoping, --watch mode, embedded local LLM
Next	GitHub Issues export from TASKS.md, prompt language packs (ES/DE/PT)
Planned	VS Code extension, HTTP/SSE transport, PR review mode, report export
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}