dsh-plugin-knowledge-graph
A DeepSeek Harness (DSH) plugin that exposes a read_graph tool backed by a codebase knowledge graph. The graph tracks every file, directory, exported symbol, and their relationships so an agent can answer structural and dependency questions faster than grepping or reading files.
> Status: infancy. This project is in its infancy stage. Execution behavior, the query surface, and compatibility may change while the project is iterated on and tested by the open source community.
> Derived work. This project is derived from the knowledge graph tool in Luke-Yong/H, adapted to DeepSeek Harness's "everything is a plugin" model.
What it does
Given a workspace root, the plugin builds an in-memory graph and answers queries such as:
structure— print the full directory treeexports— list every symbol exported by a fileimports_of— list symbols a file imports (with their source files; stdlib/third-party imports are tagged)exporters_of— find which files export a symboldependents— find which files import from a fileunused_imports— list imports never referenced in the file
Symbols are parsed from TypeScript/JavaScript (via the TypeScript compiler API) and Python (module-level def, class, and name = value bindings).
Graph model
The graph uses three node types and four edge types:
| Nodes | Meaning |
|---|---|
dir |
A directory |
file |
A source file |
symbol |
An exported symbol (function, class, const, type, interface, enum, default) |
| Edges | Meaning |
|---|---|
CONTAINS |
Structural parent → child (dir → dir/file, file → symbol) |
EXPORTS |
File → symbol it exports |
IMPORTS |
File-level dependency (file → file) |
IMPORTS_SYMBOL |
Precise symbol-level dependency (file → symbol) |
Installation
Install with the DSH CLI into a profile:
dsh plugin --profile web add github:Luke-Yong/dsh-plugin-knowledge-graph
Pin to a specific commit for reproducibility:
dsh plugin --profile web add github:Luke-Yong/dsh-plugin-knowledge-graph#
Usage
The plugin registers a single tool, read_graph, on ctx.tools. Its parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | yes | Query string in |
root |
string | no | Absolute workspace root to graph. Defaults to process.cwd() |
> Root hygiene: the root default (process.cwd()) may be a parent directory containing several independent projects. Always pass an explicit root pointing at the single workspace you are working in, so structure doesn't descend into sibling trees.
Example queries:
exports src/index.ts
exporters_of buildKnowledgeGraph
imports_of src/query.ts
dependents src/knowledgeGraph.ts
unused_imports app.py
structure
Project structure
src/
index.ts Plugin entry — registers the read_graph tool
knowledgeGraph.ts Graph builder (filesystem walk, import/export parsing, serialization)
query.ts Query engine (runGraphQuery)
Building
npm run build # tsc -p tsconfig.json
Output is emitted to dist/ (dist/index.js is the package entry point).
License
MIT
