dsh-plugin-codegraph

A DeepSeek Harness plugin that exposes the local CodeGraph CLI as model-facing tools.

CodeGraph is a 100% local code-intelligence engine: it indexes a project's symbols and their relationships into a .codegraph/ knowledge graph and answers structural questions (where is X, what calls Y, what breaks if I change Z, show me the area around W) in far fewer tokens and round-trips than grep/read loops. This plugin shells out to the codegraph binary, so the agent gets the same power as CodeGraph's own MCP server — no extra daemon to manage.

Tools provided

Tool	Description
codegraph_status	Index health check (initialized, file/node/edge counts, languages, pending changes). Always exits successfully.
codegraph_init	Initialize CodeGraph in a project directory and build the initial index.
codegraph_sync	Incrementally sync an existing index with recent changes (fast).
codegraph_search	Quick symbol search by name — locations only, no code.
codegraph_explore	PRIMARY tool — verbatim, line-numbered source of relevant symbols + call paths in one capped call.
codegraph_node	Read ONE symbol (source + caller/callee trail) or ONE whole file (line numbers + dependents). Use instead of Read for indexed source files.
codegraph_files	Indexed file structure (path, language, symbol count, size).
codegraph_callers	List the functions/methods that call a symbol.
codegraph_callees	List the functions/methods a symbol calls.
codegraph_impact	Blast-radius analysis — what is affected by changing a symbol.

Every tool accepts an optional path (project root, or any folder inside it) to target a specific codebase; omit it to use the configured default project.

Prerequisites

1. DeepSeek Harness installed (dsh CLI available).
2. CodeGraph installed and on PATH:

   curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
   # or: npm install -g @colbymchenry/codegraph
   codegraph version   # sanity check
   

3. pnpm available (DSH plugin management uses pnpm under the hood).

Installation

From a local directory (development)

cd /path/to/dsh-plugin-codegraph
dsh plugin --profile <name> add ./dsh-plugin-codegraph

From a git repository

dsh plugin --profile <name> add git+https://github.com/you/dsh-plugin-codegraph.git

From the npm registry (when published)

dsh plugin --profile <name> add dsh-plugin-codegraph

Verify the layer composed into your profile:

dsh --profile <name> --dump-config   # look for a "# == dsh-plugin-codegraph" layer

Remove later with dsh plugin --profile <name> remove dsh-plugin-codegraph.

Configuration

The plugin reads config from the tool-codegraph entry it contributes (see cordis.patch.yml). Override any value from your profile's cordis.patch.yml:

- id: tool-codegraph
  config:
    binPath: 'codegraph'          # codegraph binary (PATH-resolved)
    defaultProjectPath: ''        # empty = harness working directory
    timeoutMs: 60000              # query tools
    indexTimeoutMs: 300000        # init/sync on large repos
    defaultLimit: 10              # symbol search limit

Patch layers replace the whole config value for a row, so restate every key you want to keep.

Usage

1. Install the plugin

dsh plugin --profile web add ./dsh-plugin-codegraph

2. Make sure the target project is indexed

The agent can check and (with your go-ahead) build the index:

Is my project at /home/me/myapp indexed by CodeGraph?

or directly from a shell:

cd /home/me/myapp
codegraph init          # first time
codegraph sync          # after edits

3. Ask structural questions

How does authentication work in this codebase?
Who calls the `parseConfig` function?
What would break if I change `SessionStore.get`?

The agent routes these to codegraph_explore / codegraph_callers / codegraph_impact automatically.

Development

npm install        # resolves peer deps for local testing
node test-plugin.mjs

The smoke test boots apply() against a fake Cordis context and executes every tool against a small indexed project (CG_TEST_PROJECT, default /tmp/cg-test). To build the test project:

codegraph init /tmp/cg-test

Architecture

┌──────────────────────────────────────────┐
│  DeepSeek Harness agent                  │
│  ┌────────────────────────────────────┐  │
│  │  dsh-plugin-codegraph              │  │
│  │  - 10 tool definitions             │  │
│  │  - CLI runner (lib/client.js)      │  │
│  └──────────────────┬─────────────────┘  │
│                     │ spawn(codegraph)   │
└─────────────────────┼────────────────────┘
                      ▼
        ┌─────────────────────────────┐
        │  codegraph CLI (local)      │
        │  .codegraph/ SQLite index   │
        └─────────────────────────────┘

License

MIT