dsh-tool-codegraph

CodeGraph navigation tools for DeepSeek Harness.
A DSH plugin that wraps the open-source codegraph CLI (an AST/tree-sitter code index) into ten focused agent tools — status, search, callers/callees, impact, explore, and more.

This package is a thin wrapper. All indexing and querying is done by the codegraph CLI — install it first and make sure its binary is on PATH.

---

⚡️ Highlights

• 🧭 Orientation-first workflow — usage rules (status → sync → explore → targeted lookups) are injected into the agent system prompt automatically.
• 🧰 Ten focused tools, one per operation — no mega-tool with an action parameter.
• ⚡ O(1) indexed lookups — light outputs for the main session, heavy explore builds routed to subagents.
• ⚠️ Honest about soundness — callers/callees/impact can miss dynamic-dispatch edges; the prompt tells the model when to fall back to grep.

🛠 Requirements

• Node ^22.19 || >=24
• The codegraph CLI available on PATH (override via the executable config key)

🚀 Quick Start

1. Install the plugin

dsh plugin add --profile web @m1khal3v/dsh-tool-codegraph

2. Check the wrapped CLI

codegraph status

If the binary is missing, the tools reply with an install hint and the agent falls back to grep-based search.

3. Initialize the index — your call

There is deliberately no init tool in the set above: following the codegraph project's own recommendation, indexing should be kicked off by the user, not by an agent. When codegraph status reports a missing index, run it yourself:

codegraph init

Until you do, the tools report the missing index and the agent keeps working with other search tools.

🧰 Tools

Tool	Purpose	Output
codegraph_status	Index health and statistics	light
codegraph_sync	Sync changes since the last index	long
codegraph_search	Find a symbol by name	light
codegraph_explore	Map an area with verbatim source and call paths	heavy
codegraph_callers	Who calls this symbol (unsound)	light
codegraph_callees	What this symbol calls	light
codegraph_impact	Blast radius of changing a symbol	light
codegraph_node	One symbol's details or a file view	light
codegraph_files	Project file structure from the index	light
codegraph_affected	Find test files affected by changed source files	light

⚙️ Configuration

Key	Default	Description
executable	codegraph	Binary name or path of the wrapped CLI
queryTimeoutMs	10000	Timeout for regular commands
initTimeoutMs	60000	Timeout for init / sync

🧑‍💻 Development

pnpm install
pnpm run verify    # typecheck + test
pnpm run build

📄 License

MIT

Built on top of colbymchenry/codegraph.