dsh-code-index

English | 中文

Give your DeepSeek Harness (dsh) agent the right code context for the task and the repository it is working in. code_context turns a plain-language task into a compact set of relevant symbols, files, relationships, changes, and likely tests. code_change_context starts from the current Git changes and shows what changed and what may be affected.

• Stay on the right project: repository and worktree context follows the active DSH session, so switching projects does not mix symbols or Git changes.
• Stay up to date: files added, changed, or deleted outside DSH appear in later queries without a manual rebuild.
• Choose the tool surface: full (default) keeps every tool available; compact focuses on code_index and code_context, with optional code_health.
• Keep indexing local: no embedding service, vector database, or extra indexing API key.

On this page

• 🚀 Quick start
• 🧭 Project isolation and live updates
• 👀 See it in action
• 🧰 Tools
• Configuration
• Supported languages
• How it works
• Known limitations
• Feedback

Quick start

Requires dsh and Node ≥ 22. Install the published plugin in your Web profile:

npx @deepseek-ai/dsh plugin --profile web add dsh-code-index

Restart the Web UI with npx @deepseek-ai/dsh web. For local checkout installation, compatibility details, and startup checks, see Install.

Project isolation and live updates

Open repo A → search finds A's symbols
Switch to repo B → search finds B's symbols, not A's
Edit files outside DSH → the next query sees the change
Switch back to A → A's context is still isolated

Each Git worktree gets its own index and change state. The plugin watches projects accessed by the session and checks file metadata on tool calls, so additions, edits, and deletions become visible without a manual rebuild.

See it in action

Ask: “Which repo are we in? Run code_map, then find where extractSymbols is defined.”

code_map → ranked files and key symbols
code_search("extractSymbols") → src/extract.ts:121

The same index can trace callers and callees:

Tools

Tool	Purpose
code_index	Status / (re)build the index for the current workspace
code_symbols	List symbols (functions, classes, interfaces, types, methods…) with file:line — filtered by name, path, kind, exported
code_search	Ranked lookup: exact > prefix > substring > subsequence-fuzzy, exports first, relevance score + file:line
code_map	Bounded ranked repo map (top files by symbol density + import-graph PageRank, key symbols + lines)
code_refs	Trace a symbol through the call graph: callers (who calls it) and callees (what it calls), resolved to file:line
code_change_context	Start from the working-tree or an explicit diff and return changed symbols, callers, import dependents, bounded impact paths, and likely tests
code_context	Task-aware unified entry point: routes a plain-language task across search, repo map, call/import graph, change context, tests, and a hard character budget
code_health	Opt-in (codeHealth: true): circular dependencies (import cycles) and orphan modules

Plus an optional auto-injected system prompt section (code-index:repo-map, order 60): a compact ranked map selected from the active DSH session workspace. Set autoInject: false to disable and rely on the code_map tool only.

Install

Requires dsh (any install path — npx, npm, or source) and Node ≥ 22.

The development compatibility target is @deepseek-ai/dsh@0.1.7-alpha.2 / @deepseek-ai/dsh-tools@0.1.7-alpha.2 (Node 22 and 24 CI matrix). The DSH plugin surface is still a preview API, so upstream changes may require compatibility updates.

# from npm (prebuilt)
npx @deepseek-ai/dsh plugin --profile web add dsh-code-index

# or from a directory containing this checkout
npx @deepseek-ai/dsh plugin --profile web add ./dsh-code-index

Restart the Web UI (npx @deepseek-ai/dsh web) — startup logs confirm each tool:

[dsh-code-index] plugin loaded
[dsh-code-index] registered tool: code_index
...

Verify the composed config without booting: dsh --profile web --dump-config.

Using it

In a workspace session, ask the agent:

• "Which repo are we in — run code_map first."
• "Find every function whose name contains parse and where it lives."
• "List the exported symbols in src/core."
• "Rebuild the code index."
• "What changed in the working tree, who calls it, and which tests are likely affected?"
• "Fix duplicate configuration loading during startup." (the router selects the smallest useful context automatically)

No API key is needed to index; the model must of course be configured to call the tools.

More capabilities

The index builds lazily on first use; later calls are served from the on-disk cache with mtime-incremental refresh.

Call graph

code_refs traces a symbol through the call graph — the run below is on this repo itself (getIndex is defined at src/tools.ts:105, called from 7 sites, and its callee resolves to src/tools.ts:74):

The screenshot above shows definitions, callers, and callees resolved to file:line.

Change-aware context

code_change_context defaults to the current Git working tree against HEAD. It also accepts an inline unified diff, repo-relative files, or stable symbols IDs. Results are bounded and each inferred relationship carries a provenance label: exact, import-scoped, or name-only. Deletions and renames use the baseline ref when available; untracked non-ignored files are included in working-tree mode.

Task-aware context

code_context is the high-level entry point for agents that have a task rather than a symbol query. The deterministic router recognizes change, symbol, architecture, test, exploration, and ambiguous tasks, then ranks existing primitives into one bounded package:

code_context { task: "Fix duplicate configuration loading during startup" }

Task context — change
Primary symbols:
- [exact] function loadConfig() — src/config.ts:42
Relevant files:
- src/config.ts (current change)
- src/bootstrap.ts (entry path)
Relationships:
- bootstrap → loadConfig at src/bootstrap.ts:18 [exact; explicit-import-binding]
Current changes:
- modified function loadConfig() src/config.ts:42 [exact]
Likely affected tests:
- tests/config.spec.ts
Budget: 3720 / 5000 chars

The budgetChars, maxFiles, and maxSymbols arguments are optional. code_context does not call an external model or API; exact, import-scoped, and name-only provenance remains explicit for inferred relationships.

Configuration

Options are passed as the plugin row's config in the profile patch (or defaults are used if absent):

# $DSH_HOME/profiles/<name>/cordis.patch.yml — a bare row overrides by id.
- id: code-index
  config:
    excludeDirs: [generated, playground]
    mapTopFiles: 30
    mapMaxChars: 4000
    autoInject: true
    toolSurface: full

Key	Default	Meaning
excludeDirs	[]	Extra directory names appended to built-in excludes. Matching is by exact path component; glob patterns such as secrets/** are not supported.
mapTopFiles	24	Max files in a ranked map
mapMaxChars	3200	Hard cap on rendered map characters
mapTtlMs	60000	Refresh interval for the auto-injected map (ms, min 1000)
autoInject	true	Register the system prompt section
codeHealth	false	Register the code_health tool (cycles / orphan modules)
toolSurface	full	Experimental compact mode exposes code_index, code_context, and enabled code_health; full preserves all tools
externalWatch	true	Watch source files in active project contexts for external edits
watchDebounceMs	120	Coalesce watcher events before refreshing affected files (minimum 20 ms)

Supported languages

TypeScript, JavaScript, Python, Go, Rust, Java, C++ and C (.ts .tsx .mts .cts .js .jsx .mjs .cjs .py .pyi .go .rs .java .cpp .cc .cxx .c++ .hpp .hxx .hh .h .ipp .tpp .inl .c) via tree-sitter WASM — pure parsing, no native build. The symbol provider seam (src/extract.ts + grammars) is where other languages/embeddings plug in later. C/C++ symbol extraction resolves names through the declarator chain (templates, qualified ns::name definitions, in-class methods), and #include "…" specifiers feed the repo-map reference graph.

How it works

• Index build (src/buildIndex.ts): recursive scan (excludes applied), per-file tree-sitter extraction (src/extract.ts), JSON cache under <repo>/.dsh-code-index/, incremental refresh by mtime (only touched files re-parse).
• Search (src/search.ts): pure scoring — exact 1 / prefix 0.8 / substring 0.5, export boost, name order tiebreak.
• Repo map (src/repomap.ts): personalized PageRank over the import graph (teleport = per-file density share, so hub files that are themselves imported by other hubs rise above flat in-degree counting), seeded by the density-aware file score (class/interface/function weighted, test paths damped), top-N files, per-file symbol cap, hard char truncation.
• Call graph (src/refgraph.ts): call sites extracted per file (per language, with their enclosing function) are resolved by name into callers and callees — code_refs exposes this directly, and code_search uses call fan-in as a ranking tie-break.
• Change context (src/change-context.ts): maps Git hunks to stable symbols, then follows bounded provenance-labeled callers, import dependents, entry paths, impact, and likely affected tests without returning the whole repository.
• Task-aware context (src/context.ts): deterministically routes a task across the existing search, map, call graph, change context, and test signals, then deduplicates and trims them to a hard character budget.
• Health (src/health.ts): Tarjan SCC over the import graph yields circular dependencies; orphan-module detection lists symbol-bearing files with no inbound or outbound imports (entry points and tests excluded).
• Workspace resolution: each tool resolves the session cwd (agent.session.header.cwd) and walks up to the nearest .git (bounded — a directory without a repo marker is never indexed).
• Project contexts (src/repo-context.ts): canonical real paths identify separate worktrees; up to four contexts are retained. Each tool call scans current metadata and reparses only changed files, while the watcher refreshes dirty files after a bounded debounce.
• Ignore handling: Git ignore rules from root and nested .gitignore files are applied to indexing. excludeDirs remains a list of exact directory names, not glob patterns.

Known limitations

• web-tree-sitter pinned to ^0.25 (ESM) — the 0.25 line uses ESM named exports (Language/Query); this pairing with tree-sitter-wasms static builds is verified working under Node ≥ 22/24.
• Auto-injected maps use DSH's system-prompt assembly context for the active session. Agentless assembly falls back to the DSH process working directory. A newly accessed project may have an empty map on its first prompt while indexing completes; following assemblies receive its map.
• The watcher starts only for projects accessed by a tool and is disposed with the plugin. With externalWatch: false, per-call metadata scans still detect ordinary mtime changes.
• Large monorepos still require a directory metadata scan on each tool call. File parsing is incremental, but scan latency depends on repository size and storage speed.
• Local variables are indexed too — recall over precision; code_search ranking keeps them low.

Development

pnpm install
pnpm test        # vitest — extractor, scan, cache, search, repo map, call graph, health
pnpm typecheck
pnpm build       # tsup → dist/index.js (ESM, external deps)
pnpm build && pnpm release:smoke # pack, clean-install the tarball, boot the plugin, and exercise core tools

The benchmark harness under bench/ compares stock DSH, the published 0.5 baseline, the v0.6 change-aware treatment, and the v0.7 task-aware treatment. It records task completion, input tokens, tool calls, turns, and wall time; it does not invent missing provider usage. The repository contains infrastructure and sample tasks, not measured performance claims.

WSL → Windows checkouts: running pnpm install from WSL against a checkout on /mnt/c leaves Linux-style symlinks that Windows Node cannot traverse (Cannot find package 'web-tree-sitter', EACCES). Repair without a reinstall from the Windows side:

node.exe scripts\fix-wsl-links.mjs            # this repo's node_modules
node.exe scripts\fix-wsl-links.mjs C:\Users\you\.dsh\profiles\web   # a dsh profile install

It re-points every dead link at its real .pnpm store entry as a junction; safe to re-run (idempotent, reports fixed: 0 when clean).

Feedback

Used dsh-code-index? Tell me what helped, what broke, or what context it missed. Reply in the official DSH plugin discussion, or use the feedback issue form if issue submissions are enabled for the repository.

To make a report actionable, include the approximate repository size and languages, the task you tried, the context you expected, and what the agent actually received. Mention whether project switching, a worktree, or an external file edit was involved. Please do not include private source code, credentials, or API keys.

License

MIT. Not affiliated with DeepSeek; built on the public dsh plugin surface.