QuantumKuba/dsh-graphify-plugin

Give DeepSeek Harness a current, local map of your codebase.

dsh-graphify connects Graphify's code knowledge graph to DeepSeek Harness (DSH). It helps an agent move from a question to the relevant symbols, dependencies, architectural communities, and change impact without treating a repository as an unstructured pile of files.

Why use it?

Graphify is the local graph engine; dsh-graphify is the DSH-native layer that makes it practical in an agent session.

With a raw code search workflow	With dsh-graphify
The agent repeatedly guesses paths, greps, and reads broad files.	The agent can start from symbols, dependency paths, communities, and graph-backed project context.
A graph can silently describe an older checkout.	Freshness checks identify stale graphs and can warn or safely run an incremental code update.
Every graph capability is exposed, even when a smaller model needs only navigation.	Compact mode provides six focused tools for local 20B–30B models; full mode exposes the complete set.
MCP setup and failures are separate from the DSH session.	The plugin resolves the active session project, manages the Graphify process, and provides graphify_status for diagnosis.

This is not a claim that a graph replaces source reading or tests. It gives the agent a reliable starting map, so it can spend its context budget on the code that matters.

Install and use it

Before you start

You need a working DSH profile, Node.js 22.18 or later, Python 3.10 or later, and uv. The plugin is tested on macOS and Ubuntu Linux; Windows is not yet verified.

1. Add the plugin to your DSH profile

dsh plugin --profile <profile> add dsh-graphify

For example, replace <profile> with the profile you normally use to run DSH. The bundle activates itself; you do not need to hand-edit a Cordis configuration for the default setup.

2. Install the local Graphify runtime

uv tool install 'graphifyy[mcp]==0.9.57'

If Graphify is unavailable, DSH can still start. Ask for graphify_status after installing it; the plugin discovers the runtime on the next check or tool call, without a DSH restart.

3. Build a graph for a repository

Start DSH from the repository you want to explore:

cd /path/to/your/repository
dsh --profile <profile>

Then, in the DSH conversation, run:

/graphify

The command performs a full build and writes graphify-out/graph.json in that repository. Check the result with:

graphify_status

4. Ask architectural questions

Try requests that benefit from relationships instead of filename matching:

What are this repository's entry points and the most connected modules?

Before I change this interface, show the dependency path to its callers and summarize the likely blast radius.

Which community owns authentication, and where does it connect to the API layer?

Pick a mode

The default full mode exposes the complete Graphify capability set, including communities, god nodes, and pull-request impact. Use it when your model has ample tool-selection capacity or you need those specialist queries.

For local 20B–30B models, use compact. It registers six high-frequency tools: status, graph query, node inspection, neighbours, shortest path, and the session-scoped graph resource. Fewer choices help smaller models use the graph consistently.

Add an override only when you need one:

- insert:
    - id: dsh-graphify
      name: dsh-graphify
      config:
        toolMode: compact
        freshness:
          mode: warn

freshness.mode is warn by default. Choose auto when you want the plugin to coalesce safe incremental updates before a query; choose off only when you deliberately accept a static graph. A full /graphify build is required after documentation or other non-code changes, because incremental Graphify updates cover code extraction only.

What the plugin adds

• Session-aware project resolution: graph requests follow the active DSH workspace. Model-invoked access outside that workspace is blocked by default.
• Freshness you can inspect: graphify_status reports the resolved project, graph path, runtime availability, connection state, and whether the graph matches the indexed source state.
• Safe update policy: incremental updates run only for changes the plugin can prove are code-only; otherwise it keeps the graph marked stale and asks for a full build.
• DSH-native operation: /graphify builds or updates the receiving session's project and shows its durable result in DSH Web.
• Resilient local runtime: the plugin discovers Graphify automatically and reconnects after unexpected MCP-process exits.

Common tasks

Goal	In DSH
Build or fully refresh the graph	/graphify or /graphify build
Update changed code files	/graphify update
Diagnose installation, project selection, or stale data	graphify_status
Find a symbol and related architecture	Ask the agent to query the graph, then inspect the returned nodes and paths.
Analyse a risky change	Ask for dependents, shortest paths, communities, or PR impact before editing.

/graphify update is intentionally conservative. Run /graphify after changes to Markdown, package metadata, configuration, or any other non-code source that should be represented in the graph.

Configuration reference

The defaults work for most single-repository sessions. These are the settings users commonly change:

Setting	Default	Use it when
toolMode	full	Set compact for focused navigation with smaller local models.
freshness.mode	warn	Set auto for safe pre-query code updates, or off for an intentionally static graph.
graphifyVersion	unset	Pin the Graphify version used by automatic uv fallback.
graphPath	auto-detected	Point to a non-standard graph.json location.
cwd	active session project	Supply a fallback project directory when a session has no workspace.
allowExternalProjects	false	Allow model tools to access projects beyond the session workspace.
toolPrefix	empty	Avoid tool-name collisions in a larger DSH profile.

See src/config.ts for the complete, typed configuration schema and defaults.

Troubleshooting

Symptom	What to do
graphify_status says the runtime is unavailable	Run the uv tool install command above, then run graphify_status again.
No graph is found	Start DSH in the repository and run /graphify.
The graph is stale after docs or configuration edits	Run /graphify for a full build.
The wrong project is selected	Start DSH from the intended repository, or configure cwd or graphPath.
A model needs another checkout	Keep the default isolation where possible; otherwise set allowExternalProjects: true deliberately.

Compatibility and development

The package supports @deepseek-ai/cordis >=4.0.4 <5, is tested against DeepSeek Harness 0.2.0-rc.2 (and the 0.2.1-alpha channel), and is tested with Graphify 0.9.57 (live contract and schema-drift checks also pass on 0.9.90). It ships a prebuilt DSH bundle and can be developed locally with:

pnpm run typecheck
pnpm run build
pnpm test
pnpm run test:drift

Use GRAPHIFY_E2E=1 pnpm run test:e2e to exercise a live local Graphify installation. Contribution guidance is in CONTRIBUTING.md.

Evidence and next steps

BENCHMARK.md defines the planned, reproducible evaluation of Graphify-assisted agents against the baseline. It is an experimental protocol, not performance results. For Graphify's graph engine, supported languages, and upstream CLI documentation, visit Graphify.