<p align="center">
  <a href="https://shinzarou-eng.github.io/dsh-codebase-chat">
    <img src="https://raw.githubusercontent.com/shinzarou-eng/dsh-codebase-chat/main/docs/assets/social-preview.png" alt="dsh-codebase-chat — Your codebase, fully understood" width="100%">
  </a>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/dsh-codebase-chat"><img src="https://img.shields.io/npm/v/dsh-codebase-chat?logo=npm&label=plugin&color=6ec2ff" alt="npm plugin"></a>
  <a href="https://www.npmjs.com/package/dsh-codebase-chat-mcp"><img src="https://img.shields.io/npm/v/dsh-codebase-chat-mcp?logo=npm&label=mcp&color=a78bfa" alt="npm mcp"></a>
  <a href="https://github.com/shinzarou-eng/dsh-codebase-chat/blob/main/LICENSE"><img src="https://img.shields.io/github/license/shinzarou-eng/dsh-codebase-chat?color=93a1b5" alt="license"></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-4ade80?logo=nodedotjs" alt="node >= 20"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-22d3ee" alt="MCP compatible"></a>
  <a href="https://github.com/shinzarou-eng/dsh-codebase-chat/stargazers"><img src="https://img.shields.io/github/stars/shinzarou-eng/dsh-codebase-chat?style=social" alt="stars"></a>
</p>

<p align="center">
  <a href="https://shinzarou-eng.github.io/dsh-codebase-chat"><strong>Website</strong></a> ·
  <a href="#install-in-one-command">Install</a> ·
  <a href="#tool-suite">Tools</a> ·
  <a href="ROADMAP.md">Roadmap</a> ·
  <a href="CHANGELOG.md">Changelog</a> ·
  <a href="CONTRIBUTING.md">Contributing</a>
</p>

<br>

<h2 align="center">Install in one command</h2>

<p align="center">Works with <strong>Claude · Cursor · Windsurf · VS Code · DeepSeek Harness</strong> — no API key required.</p>

```bash
npx dsh-codebase-chat-mcp setup
```

<p align="center">
  <sub>The wizard detects your IDE and writes the MCP config for you — no JSON to edit.<br>
  Prefer manual? <a href="#manual-mcp-config">Paste a config block</a> · <a href="mcp/README.md">MCP docs</a></sub>
</p>

<p align="center">
  <img src="docs/assets/demo.gif" alt="dsh-codebase-chat CLI demo" width="840"><br>
  <em>Real terminal output — <a href="docs/assets/demo-mcp.gif">MCP session</a> · <a href="docs/assets/demo-fr.gif">French mode</a></em>
</p>

<br>

<h2 align="center">Real output — no mockups</h2>

<p align="center"><sub>What the tools actually return inside your IDE.</sub></p>

<table>
<tr>
<td width="50%" valign="top">

<p align="center"><strong><code>codebase_health</code></strong><br><sub>deterministic analysis — runs fully offline</sub></p>
<img src="docs/assets/output-health.png" alt="codebase_health report" width="100%">

</td>
<td width="50%" valign="top">

<p align="center"><strong><code>codebase_chat</code></strong><br><sub>every claim carries a receipt</sub></p>
<img src="docs/assets/output-chat.png" alt="codebase_chat cited answer" width="100%">

</td>
</tr>
</table>

<p align="center"><strong><code>codebase_intelligence</code></strong> — full CTO brief: architecture map, strengths, ranked risks, 90-day plan</p>
<img src="docs/assets/output-intel.png" alt="codebase_intelligence CTO brief" width="100%">

<br>

<h2 align="center">What is this, exactly?</h2>

<p align="center"><sub>In plain words — no jargon required.</sub></p>

> [!NOTE]
> Point it at a folder of code on your computer. Ask questions like a
> human — *"How does login work?"*, *"Is there a hardcoded password?"*, *"What should I fix
> first?"* — in French or English. Every answer cites the exact **file and line** it came
> from, so you can verify it in seconds. **Nothing is uploaded anywhere.**

<details>
<summary><strong>🇫🇷 En termes simples</strong></summary>
<br>

Pointez-le vers un dossier de code sur votre ordinateur. Posez des questions en langage
clair — *« Comment fonctionne la connexion ? », « Y a-t-il un mot de passe codé en dur ? »,
« Que devrais-je réparer en premier ? »* — en français ou en anglais. Chaque réponse cite
exactement le fichier et la ligne d'où elle vient. **Rien n'est envoyé sur internet.**

</details>

<br>

| Term | Plain meaning |
| --- | --- |
| **MCP server** | A plug format that lets AI assistants (Claude, Cursor…) use extra tools. Install once — your IDE can "see" your code. |
| **Index** | Like the index at the back of a book — a map of every function and file, so answers are instant. |
| **Prompt-only mode** | The tool prepares the context; your existing AI writes the answer. **No extra API key, no extra cost.** |
| **Deterministic analysis** | Checks computed directly from your code — same input, same result, every time. No guessing. |

<br>

<h2 align="center">Why dsh-codebase-chat?</h2>

<p align="center"><sub>Most codebase assistants are slow, paywalled, or upload your source to the cloud.<br>
This one runs entirely on your machine — and every answer comes back sourced.</sub></p>

| | |
| --- | --- |
| **Local-first** | Indexing, retrieval and prompt building never leave your machine. |
| **Bilingual** | Every prompt, report and UI string in French and English. |
| **Everywhere** | DeepSeek Harness plugin, MCP server (Cursor, Claude, Windsurf…), plain CLI. |
| **Decision-grade** | Not just answers — CTO briefs, audits, TASKS.md plans, board reports. |
| **Zero-cost mode** | Prompt-only: your host model does the thinking. No API key needed. |
| **Real AST** | Babel for JS/TS + tree-sitter WASM for Python, Go, Rust, Java, C#, PHP. |

<br>

| | Paste code into a chat | Hosted code assistant | **dsh-codebase-chat** |
| --- | :-: | :-: | :-: |
| Sees your **whole** repo, not one file | ❌ | ✅ | ✅ |
| `[source: file:line]` citations | ❌ | ~ | ✅ |
| Code stays on your machine | ❌ | ❌ | ✅ |
| Works inside Claude / Cursor / Windsurf | ❌ | ~ | ✅ |
| Deterministic health score, no LLM | ❌ | ❌ | ✅ |
| Free, no API key required | ~ | ❌ | ✅ |

<br>

<h2 align="center">Tool suite</h2>

<p align="center"><sub>12 tools — available as DSH tools, slash commands, and MCP tools.</sub></p>

| Understand | Decide |
| --- | --- |
| `codebase_chat` — Q&A with cited sources | `codebase_intelligence` — full CTO brief: architecture, debt, security, roadmap |
| `codebase_search` — symbols & usages repo-wide | `codebase_audit` — tech-debt scan with severity |
| `codebase_explain` — file/symbol explanation | `codebase_report` — board report: SWOT, risks, opportunities |
| `codebase_health` — **deterministic** static analysis, no LLM | `codebase_ceo` — one-page executive brief |

| Act | Explore |
| --- | --- |
| `codebase_refactor` — concrete refactor + Before/After diff | `codebase_player` — UX playthrough brief, user's POV |
| `codebase_tasks` — sprinted `TASKS.md` action plan | `codebase_crea` — creative & marketing angles from the code |

<sub>Common parameters: `projectPath`, `lang` (`fr`/`en`), `embed` (local embeddings), `promptOnly` (MCP), `maxTokens` (context budget).</sub>

<details>
<summary><strong>Slash commands (DeepSeek Harness)</strong></summary>
<br>

```powershell
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'
```

</details>

<br>

<h2 align="center">How it works</h2>

<p align="center"><sub>Everything left of the dashed line runs <strong>on your machine</strong>.<br>
Nothing crosses it except the assembled prompt — and in prompt-only mode, not even that.</sub></p>

```mermaid
flowchart LR
    subgraph LOCAL["Your machine — local-first"]
        direction TB
        A["Source files<br/><sub>JS · TS · Py · Go · Rust · Java · C# · PHP</sub>"]
        B["AST index<br/><sub>Babel + tree-sitter WASM<br/>incremental cache</sub>"]
        C["Retrieval<br/><sub>lexical + local embeddings<br/>token-budgeted</sub>"]
        D["Sourced briefing<br/><sub>module graph · metrics · debt signals</sub>"]
        H["Deterministic analysis<br/><sub>cycles · dead code · duplication · score</sub>"]
        A --> B --> C --> D
        B --> H
    end

    D -->|"promptOnly (default)"| F["Host model<br/><sub>Claude · Cursor · Windsurf · Devin</sub>"]
    D -->|"API key set"| G["DeepSeek / OpenAI"]
    F --> R["Cited answer<br/><sub>[source: file:line] · [Confidence] · [Severity]</sub>"]
    G --> R
    H -.->|"no LLM needed"| R

    style LOCAL fill:#0b0e14,stroke:#4ade80,stroke-width:2px,stroke-dasharray:6 4
    style R fill:#0f1a12,stroke:#4ade80
    style D fill:#10141c,stroke:#fbbf24
```

| Step | What happens |
| --- | --- |
| **1 · Index** | Real AST extraction maps every function, class and import — cached on disk, refreshed incrementally (mtime/size based, no full re-reads). |
| **2 · Retrieve** | Lexical scoring + optional local multilingual embeddings pick the chunks that matter inside your token budget. |
| **3 · Prompt** | A language-aware briefing is assembled — module graph, metrics, debt signals, file excerpts, citation rules. |
| **4 · Answer** | Your model responds with `[source: file:line]`, `[Confidence: X%]`, `[Severity: …]` — verifiable in seconds. |

**Safe apply pipeline** — `/codebase-apply` and `/codebase-apply-tasks` support dry-run,
create `.dsh-backups/` copies before overwriting, enforce protected paths, and never write
outside the selected project.

<br>

<h2 align="center">Quick start</h2>

<table>
<tr>
<td width="50%" valign="top">

**MCP server — recommended**

```bash
npx dsh-codebase-chat-mcp setup
```

Detects Claude, Cursor, Windsurf, VS Code and writes the config. No API key — prompt-only mode.

</td>
<td width="50%" valign="top">

**DeepSeek Harness plugin**

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

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

</td>
</tr>
<tr>
<td width="50%" valign="top">

**CLI**

```bash
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
```

First run builds a cached index; subsequent runs are incremental.

</td>
<td width="50%" valign="top">

**From source**

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

</td>
</tr>
</table>

### Manual MCP config

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

> [!TIP]
> **No API key needed.** Without `DEEPSEEK_API_KEY` / `OPENAI_API_KEY`, the server runs in
> `promptOnly` mode and hands the assembled context to your host model. See
> [`mcp/README.md`](mcp/README.md) for direct-LLM configuration.

<br>

<h2 align="center">Configuration</h2>

<p align="center"><sub><code>.codebase-chat.json</code> — per-project settings. Every key optional.</sub></p>

```json
{
  "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` or `fr`) for CLI, MCP tools and slash commands |
| `maxTokens` | Default context budget when the caller passes none |
| `ignoreDirs` | Extra directory names skipped by indexing, `codebase_health` and the file tree |
| `ignoreFiles` | Extra file names skipped the same way |
| `ignoreGlobs` | Globs on project-relative paths — `**` spans directories, `*` one segment, `?` one char |
| `protectedPaths` | Extra paths the apply pipeline can never patch |

<details>
<summary><strong>Environment variables</strong></summary>
<br>

| Variable | Default | Purpose |
| --- | --- | --- |
| `CODEBASE_CACHE_DIR` | OS cache dir | Where the index cache lives |
| `DSH_PROJECT_ALIASES` | — | Extra `name=path` project aliases (`;`-separated) |
| `DSH_DAKO_PROJECT` | — | Override the built-in `dako` alias target |
| `DSH_PROTECTED_PATHS` | built-in list | Extra paths that can never be patched |
| `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` | — | MCP 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 |

</details>

<br>

<h2 align="center">Project layout</h2>

```
├── 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)
```

```bash
pnpm install      # install workspace deps
pnpm build        # tsup → dist/
pnpm test         # vitest run
pnpm typecheck    # tsc --noEmit
```

<br>

<h2 align="center">FAQ</h2>

<details>
<summary><strong>Does it send my code to the cloud?</strong></summary>
<br>
No. Indexing, retrieval, and prompt building run on your machine. In MCP prompt-only mode, nothing leaves your machine at all — the host model reads the assembled context directly.
</details>

<details>
<summary><strong>Do I need an API key?</strong></summary>
<br>
Not for the MCP server — without a key it returns the built prompt to the host model. A <code>DEEPSEEK_API_KEY</code> or <code>OPENAI_API_KEY</code> is only needed for direct LLM calls. Inside DeepSeek Harness, the plugin uses your configured model.
</details>

<details>
<summary><strong>Which languages are supported?</strong></summary>
<br>
French and English out of the box via the <code>lang</code> parameter on every tool and command. Source-side, AST extraction covers JS/TS, Python, Go, Rust, Java, C# and PHP — everything else is indexed line by line.
</details>

<details>
<summary><strong>Is applying patches safe?</strong></summary>
<br>
Yes. Apply workflows support dry-run, create backups before overwriting, enforce protected paths, and keep all writes inside the selected project.
</details>

<details>
<summary><strong>Troubleshooting: EADDRINUSE on port 3080</strong></summary>
<br>

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

Then restart <code>dsh --profile web</code>.
</details>

<br>

<h2 align="center">Roadmap</h2>

| | |
| --- | --- |
| **Shipped** | tree-sitter AST (7 languages), deterministic health score, MCP setup wizard, `.codebase-chat.json` config |
| **Next** | watch mode, GitHub Issues export from TASKS.md, diff-aware retrieval |
| **Planned** | VS Code extension, HTTP/SSE transport, PR review mode, report export (HTML/PDF) |
| **Exploring** | multi-repo workspaces, shared team index cache, CI bot |

<p align="center"><sub>See <a href="ROADMAP.md">ROADMAP.md</a> for the full plan.</sub></p>

---

<p align="center">
  <br>
  <strong>If this project helps you — <a href="https://github.com/shinzarou-eng/dsh-codebase-chat">star it on GitHub</a> ⭐</strong>
  <br><br>
  <a href="https://shinzarou-eng.github.io/dsh-codebase-chat">Website</a> ·
  <a href="https://github.com/shinzarou-eng/dsh-codebase-chat/issues">Issues</a> ·
  <a href="CONTRIBUTING.md">Contributing</a> ·
  <a href="SUPPORT.md">Support</a> ·
  <a href="SECURITY.md">Security</a>
  <br><br>
  <sub><a href="LICENSE">MIT License</a> — built and maintained by <a href="https://github.com/shinzarou-eng">shinzarou-eng</a></sub>
</p>