NEW v0.29 - IDE-style --ui dashboard + Ctrl+K command palette

Your codebase,
fully understood.

Name: codebase-chat
Author: shinzarou-eng

Chat, search, explain, refactor, audit - and generate board-ready reports. Every claim carries a source citation, a confidence score, and a severity label. Your code is indexed locally - you pick the model. Fully offline mode included.

Get started View on GitHub

$ npx codebase-chat-mcp setup

one command - auto-detects your IDE and writes the config

Works everywhere you code

Cursor Claude Windsurf Any MCP client Terminal CLI DeepSeek Harness

real output - no mockups

Start here

What is this, exactly?

In plain words - no jargon required.

Point it at a folder of code on your computer. Ask questions in plain language - "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. Your repo is never uploaded - only the relevant excerpts reach whichever model you choose.

Point it at a folder

Give it any project on your computer. It reads the code and builds a map of it - nothing is uploaded anywhere.

Ask in plain language

"How does login work?", "Is there a hardcoded password?", "What should I fix first?" - in French or English.

Get answers with receipts

Every answer cites the exact file and line it came from - so you can check it yourself in seconds.

New to some of these words?

MCP server: A plug format that lets AI assistants (Claude, Cursor…) use extra tools. Install it once, and 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 instead of reading everything again.
Prompt-only mode: The tool prepares the context; your existing AI (Cursor, Claude…) 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.
Offline mode: The --no-llm report computes ~30 checks straight from your code - no model at all, same input, same output. For offline chat answers, pipe the generated prompt to a local model like Ollama.

MCP tools exposed

Packages - plugin & MCP

100%

Local-first indexing

FR / EN

Bilingual out of the box

How it works

From messy code to clear decisions

Four steps - all on your machine, before anything reaches an AI model.

Index

Real AST parsing (Babel + tree-sitter) maps every function, class and import in JS/TS, Python, Go, Rust, Java, C# and PHP - once, then only what changed.

Retrieve

Finds the code that actually matters for your question - nothing more, nothing less.

Prompt

Packs the relevant code into one briefing for the AI - with citations, in French or English.

Decide

You get an answer you can verify - every claim points to [source: file:line].

codebase-chat - my-app

$ npx codebase-chat --project . --ask "how is auth handled?"

[index] scanning 214 files… AST: babel + tree-sitter

[index] 1,847 symbols · cache fresh (12 files changed)

[retrieve] 23 chunks scored → top 8 kept (38,204 tokens)

[retrieve] src/auth.ts · src/session.ts · middleware/guard.ts

[prompt] briefing assembled - module graph + citations, en

[answer] Auth uses JWT with refresh rotation [source: src/auth.ts:42]

[answer] Tokens expire after 15 min [source: src/session.ts:18]

▍

stylized view of a real run - indexing & retrieval stay on your machine; only the assembled prompt reaches the model

Capabilities

Built for professional code reviews

More than a chat box: a full intelligence layer over your repository.

Chat & Search

Ask natural questions, find symbols, explain files - every answer cites file and line.

Static Health NEW

Deterministic analysis - circular deps, dead code, duplication, complexity, health score. No LLM needed.

Intelligence Pro

CTO-level brief: architecture, tech radar, debt map, security posture, competitor signals.

Audit & Tasks

Detect TODO/FIXME/any/debugger and generate a sprinted TASKS.md with Before/After patches.

Refactor & Apply

Production-ready refactors applied with backup, dry-run, verification, and rollback.

MCP Compatible

Standalone server for Cursor, Claude, Windsurf, Zed & co - key-free prompt-only, or deterministic reports with zero model.

Local dashboard - `--ui`

One command opens an IDE-style web app - editor tabs, status bar, Ctrl+K command palette, zen mode, 1–5 view shortcuts. Audit, health, stats, impact, ask-a-question, severity filters, exports - all clicks, no terminal. Fully local & bilingual.

Distribution

Two packages, one engine

Same intelligence core - pick the integration that fits your workflow.

codebase-chat

CLI + DeepSeek Harness plugin

✓Codebase Pro panel inside DeepSeek Harness
✓Slash commands: /codebase-intel, /codebase-audit…
✓Standalone CLI for any project
✓Safe apply: backup, dry-run, rollback
✓Per-project config - .codebase-chat.json

$ npm install codebase-chat

codebase-chat-mcp

Standalone MCP server

✓21 tools over stdio - works in Cursor, Claude, Windsurf
✓Prompt-only mode - no API key needed, the host model answers
✓Optional direct LLM calls via DeepSeek / OpenAI-compatible API
✓Local multilingual embeddings for semantic retrieval
✓setup wizard - detects your IDE, picks your answer mode, writes the config
✓Fully offline - deterministic --no-llm report, no model, no key

$ npx codebase-chat-mcp

Reference

The full tool suite

Every tool is available through the MCP server, the CLI and DeepSeek Harness.

Tool	What it does
codebase_chat	Q&A on your project with cited sources
codebase_search	Find symbols, terms, and usages across the repo
codebase_explain	Explain a file or a symbol - fallback symbol search included
codebase_refactor	Propose a concrete refactor with Before/After diff
codebase_intelligence	Full CTO brief: architecture, debt, security, roadmap
codebase_audit	Tech-debt and non-conformity scan with severity
codebase_report	Strategic board report - SWOT, risks, opportunities
codebase_ceo	One-page executive brief
codebase_tasks	Generate a sprinted TASKS.md action plan
codebase_player	UX / playthrough brief from a user's point of view
codebase_crea	Creative and marketing angles extracted from the code
codebase_health	Deterministic static analysis - cycles, dead code, duplication, complexity, health score. No LLM needed
codebase_impact	Deterministic blast radius - which files transitively depend on a target. No LLM needed
codebase_deep_audit	Deterministic full audit - ~30 analyses: git churn, bus factor, secrets, deps, per-function complexity. Pass `ui: true` for an HTML dashboard resource
codebase_check	Deterministic verify changes vs a git ref + committed baseline - blast radius, complexity, findings delta
codebase_fix	Deterministic mechanical repairs where the fix is unambiguous - dead deps, unused exports, console/debugger lines, undocumented env vars. `dry: true` previews
codebase_ignore	Deterministic silence a finding with a justification - written to `.codebase-chat/ignores.json`, commit it
codebase_doctor	Deterministic install & environment diagnostic - node, index cache, keys, tree-sitter, baseline staleness

All tools accept projectPath, lang (fr/en), embed, promptOnly, and diff.

See it in action

Real terminal output, no mockups

Every frame is the actual tool running against the bundled demo-project/.

CLI - index → stats → search → health → ask Real chat - real MCP session on a 422-file codebase: 324 circular deps found, cited answers PR review - real git repo, planted circular dep caught by --diff HEAD + live --watch MCP - real stdio session, 21 tools, no API key FR - symbol fallback + French prompts Dashboard - --ui opens the IDE-style web app: audit, health, stats, ask - all clicks, no terminal Palette - Ctrl+K commands, z zen mode, 1–5 view shortcuts

Get started

Install in seconds

Three ways to run it. All read code locally.

MCP server - setup wizard

RECOMMENDED

npx codebase-chat-mcp setup

Detects Claude, Cursor, Windsurf, VS Code and writes the config for you - no JSON to edit.

DeepSeek Harness plugin

dsh plugin --profile web add codebase-chat

From source

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

Configuration

MCP configuration

Run the setup wizard or paste this block into your IDE's MCP settings. No API key needed - the host model answers, or go fully offline with the deterministic report.

mcp.json

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

Optional env: DEEPSEEK_API_KEY, OPENAI_API_KEY, CODEBASE_MODEL - direct LLM calls.

Commands

One command per job

Run them headless in CI or interactively in any shell.

cli - any shell

$ npx codebase-chat --index
$ npx codebase-chat --search "jwt token"
$ npx codebase-chat --health  # no LLM
$ npx codebase-chat --file src/auth.ts
$ npx codebase-chat --prompt intelligence --no-llm # deep audit
$ npx codebase-chat --ui # web dashboard

deepseek harness

$ dsh '/codebase-intel'  C:\my-app
$ dsh '/codebase-audit'  C:\my-app --lang en
$ dsh '/codebase-health' C:\my-app
$ dsh '/codebase-tasks'  C:\my-app --apply
$ dsh '/codebase-report' C:\my-app

Trust

Evidence & scoring

Every technical claim, risk, and opportunity is backed by a source citation and scored for confidence and severity.

Auth uses JWT with refresh-token rotation. [source: src/auth.ts:42] Tokens expire after 15 min and live in memory, not localStorage. [source: src/session.ts:18] The refresh endpoint lacks rate limiting - brute-forceable. [source: src/routes/auth.ts:67] [Severity: High]

Source - every claim cites file & line

Confidence - scored, not guessed

Severity - risks ranked for you

What's next

Roadmap

Organized by horizon, not by date. Full detail in ROADMAP.md.

SHIPPED Recently shipped

✓Deterministic report - zero model, zero key, zero network
✓Watch mode - hot index while you code
✓Setup wizard + .codebase-chat.json
✓Diff-aware retrieval on changed files
✓IDE-style local dashboard - --ui + MCP-UI resource
✓codebase_deep_audit - ~30 deterministic analyses via MCP

NEXT Integrations & output

→GitHub Issues export from TASKS.md
→Prompt packs - ES, DE, PT
→VS Code extension - sidebar + inline explain
→HTTP/SSE transport for the MCP server
→PR review mode via GitHub API
→Report export - standalone HTML / PDF
→Interactive diff viewer in Codebase Pro

EXPLORING Longer horizon

→Multi-repo workspaces
→Shared team index cache
→CI bot - audit summaries on every PR
→Local reranker for tighter context
→JetBrains & Neovim clients

Questions

FAQ

I'm not a developer - can I still use it?

Yes. Install it, point it at a project folder, and ask questions in plain words. The reports are written for humans - founders, managers, designers and developers - not just for the person who wrote the code.

Does it send my code to the cloud?

Your repo is never uploaded. Indexing, retrieval and prompt building run on your machine - the tool itself makes no upload. When you ask for an answer, only the assembled prompt (the relevant excerpts, not the whole codebase) reaches whichever model you picked: your IDE's host model, an API key with --call, or a local model like Ollama. For zero network end to end, --no-llm and --ui compute the report locally.

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_API_KEY/OPENAI_API_KEY for direct calls (--call), or the deterministic report (--no-llm) - no model at all. Inside DeepSeek Harness, the plugin uses your configured model.

Can I use it with Claude, Cursor, or Windsurf?

Yes. Install codebase-chat-mcp and add it to your MCP server config - see the configuration block above.

Does it work without DeepSeek Harness?

Yes. The codebase-chat-mcp package is fully standalone, and the main package ships a CLI that works on any project.

Which languages are supported?

French and English out of the box via the lang parameter on every tool and command. Source-side, AST extraction covers JS/TS, Python, Go, Rust, Java, C# and PHP - everything else is still indexed line-wise.

Is applying patches safe?

Yes. Apply workflows support dry-run, create .dsh-backups/ copies before overwriting, enforce protected paths, and keep all writes inside the selected project.

Ready to understand your codebase?

One install. Eighteen tools. Your repo is never uploaded.

$ npx codebase-chat-mcp setup

Get started Star on GitHub

Your codebase, fully understood.