Introduction¶

A common approach to getting an agent to understand an unfamiliar codebase is to grep for keywords, glob for files, and then read them one by one. This process involves more than a dozen tool calls in a single round, floods the context with file snippets, and doesn’t guarantee hitting the true call chain.

CodeGraph (@colbymchenry/codegraph) takes a different approach: it first indexes the project into a code knowledge graph, and then queries by symbol, region, or call chain. A single call retrieves the line-by-line source code of relevant symbols and their call paths. The problem is that the CLI tool itself cannot be invoked by the model; it needs to be wrapped into a native tool visible to the model.

The dsh-codegraph introduced in this article is the DSH plugin that does exactly this.

What is this¶

jiangzhenguo/dsh-codegraph is a one-click installable DSH plugin (bundle) that wraps the codegraph CLI into 13 native codegraph_* tools, allowing DSH sessions to directly query the pre-indexed code knowledge graph. It also supports bootstrapping and maintaining the index (init/index/sync). The current version is 1.1.0, licensed under MIT.

Provided Tools¶

The 13 tools correspond one-to-one with the codegraph CLI commands, and the tool names are identical to the official CodeGraph MCP tools:

By default, only 4 core tools are registered: codegraph_status / codegraph_init / codegraph_sync / codegraph_explore. This trimming is based on empirical conclusions from the upstream project—codegraph_explore is the only tool that is consistently stable enough to win model calls, and the official MCP server also only exposes explore by default. A streamlined list of tools keeps guidance focused. If you need all 13 tools, configure surface: 'full'.

Instant-effective Prompt Guidance¶

Simply exposing the tools isn’t enough; the model might still take the grep reflex path. The plugin injects a high-priority guide into the system prompt (tool:codegraph, order: 98), while the guidance for DSH’s built-in file tools is concentrated in order 100–104 (read=100, write=101, edit=102, glob=103, grep=104). Placing the guidance at 98 ensures it is seen by the model before these others.

The guidance content uses a strategy validated by the upstream project: imperative phrasing (MUST use codegraph_explore INSTEAD of grep/glob/read), an anti-pattern checklist (don’t grep to “find files” first, don’t use grep to verify codegraph results—it comes from a full AST parse), and a hard stop rule for unindexed projects: if the session does not initialize itself, the session will no longer call codegraph tools; whether to index is the user’s decision.

frontload: Injecting context into the current turn first¶

Prompt guidance is still soft. Therefore, the plugin implements frontload pre-injection—a method with the highest measured adoption rate:

1. The plugin listens to the agent/inbox/inserted event. When a real user prompt enters the agent’s next-turn inbox, it performs confidence-level gating: prompts containing structural keywords (e.g., “调用 / 重构 / 依赖 / how does / who calls / refactor / trace”) trigger directly; prompts containing code-like tokens (filenames, camelCase, PascalCase, snake_case) trigger only after verification via codegraph query against the index; other prompts skip with zero overhead.
2. Upon triggering, it searches upwards from the current session cwd for the nearest .codegraph/ index root; if not found, it skips silently—the plugin will not init on its own.
3. It pre-runs codegraph_explore, wraps the result in <codegraph_context>, and injects it into the current turn, with a cap of 12,000 characters. The content the model reflexively wants to grep/read is already in the context.

There are three safety guarantees: all failure paths (no index, gating miss, CLI errors) are silent no-ops that won’t corrupt the user’s prompt; injected content is tagged to prevent self-cycling; and identical prompts entering the inbox within 10 minutes (GUI resend, re-queueing after a rejected step) are injected only once. Use frontload: false to disable entirely.

Difference from session-level MCP server¶

The official codegraph MCP server exposes 0 tools when no index is established in the workspace and prompts the model not to index itself. This plugin always exposes tools, including init/index/sync required for the model to bootstrap and maintain the index. This is the reason it chose a bundle form rather than an MCP server.

Installation and Activation¶

There are two prerequisites: DSH must be installed (this plugin is a DSH bundle, loaded with the DSH web application), and the codegraph CLI must be in PATH with a version ≥ 1.0:

npm i -g @colbymchenry/codegraph
codegraph --version    # Verify availability (≥ 1.0)

Then, install it with one command in the target profile (here, web):

dsh plugin --profile web add github:jiangzhenguo/dsh-codegraph

What this command does: dsh plugin runs pnpm add github:jiangzhenguo/dsh-codegraph inside the profile directory; because this package’s package.json declares dsh.bundle.patch, DSH’s plugin manager automatically adds it to the profile’s dsh.profile.bundles layer stack, so no manual config changes are needed. After restarting the DSH application, the model can see the codegraph_* tools in any session (4 by default on the core surface). Change --profile web to --profile tui etc. for other profiles. The README also mentions that if published to npm, you can replace the github: prefix with the package name.

To uninstall:

dsh plugin --profile web remove dsh-codegraph

Configuration is passed via a composition layer (e.g., the insert line in cordis.patch.yml):

- insert:
    - id: dsh-codegraph
      name: dsh-codegraph
      require: dsh-codegraph
      config:
        guideSearch: true    # Default true: injects system prompt guidance; false only registers tools
        surface: core        # Default core (4 tools); set to full to register all 13
        frontload: true      # Default true: automatically injects structured prompts

Typical Usage¶

1. Open a new DSH session in the project directory (cwd = project root).
2. Let the model first run codegraph_status; if not initialized, run codegraph_init.
3. Afterwards, use codegraph_explore to query code. A single call returns relevant symbol source code + call chain; with surface: 'full', you can also use codegraph_query / codegraph_node / codegraph_callers / codegraph_callees / codegraph_impact for more granular queries.
4. After changing code, use codegraph_sync. When you need to run tests, use codegraph_affected (full surface).

All tools work on the caller’s session cwd by default, but you can also explicitly pass path to point to other projects.

The plugin comes with a runtime test harness (test/run-plugin-test.mjs, real codegraph CLI + stub cordis service), covering paths like prompt injection order, tool registration for core/full surface, and frontload injection and deduplication. Run it in a profile where the plugin is installed:

CG_PROFILE_NM=<profile>/node_modules node test/run-plugin-test.mjs

Applicable Scenarios and Notes¶

Suitable project forms: DSH users who work with large codebases and frequently need to understand code via call chains; scenarios where you want to confirm the scope of impact before refactoring or renaming, or want to determine which tests to run after changes. The prerequisite is the willingness to establish and maintain a .codegraph/ index for the project.

A few points worth knowing:

• On local codegraph@1.0.1, callers/callees returning empty arrays is a CLI-side data/index feature (edge resolution for the call graph was not completed in that version), and the plugin faithfully returns the CLI’s actual output; impact can already return real affected nodes and edges.
• The plugin will not unilaterally init on unindexed projects; whether to index is up to the user, and the guidance contains the corresponding hard stop rule.
• All failure paths for frontload are silent no-ops and do not affect normal prompt processing.

Security tip: The plugin runs with the permissions of the current dsh process. It is recommended to check its source code and license (this project is MIT) before installing it to ensure it is acceptable, then load it into common profiles.

Conclusion¶

dsh-codegraph connects the “pre-indexed, query by call chain” path into DSH: the default 4 core tools keep the tool surface streamlined, while the order 98 prompt guidance and frontload pre-injection are responsible for actually getting the model to use them, rather than just hanging a few unused tools.

• Directory: https://www.skillhub.cn/plugins/jiangzhenguo/dsh-codegraph
• GitHub: https://github.com/jiangzhenguo/dsh-codegraph