dsh-codebase-chat

[

= 20">](https://nodejs.org)

Website · MCP docs · Roadmap · Changelog · Contributing

Get started

npx dsh-codebase-chat-mcp setup

The wizard detects Claude, Cursor, Windsurf and VS Code, writes the MCP config, done. No JSON to edit — and no API key: in promptOnly mode your host model does the thinking.

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

Live terminal capture — MCP session · 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	❌	❌	✅
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 12 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

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, 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

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

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? No. Indexing, retrieval, and prompt building run on your machine. In prompt-only mode, nothing leaves it at all.

Do I need an API key? Not for the MCP server — without a key it returns the built prompt to the host model. A key is only needed for direct LLM calls. 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
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