dsh-knowcode

⚡ DSH-KnowCode: Unified Code Graph & Knowledge Base for DeepSeek Harness

The most powerful codebase navigation, refactoring, and knowledge intelligence plugin for DeepSeek Harness agents.
Combines the best of Tree-sitter WebAssembly AST symbol graphs and Markdown knowledge bases into an embedded FalkorDB Cypher graph database with a tgrep-style client-server daemon and incremental file watcher.

---

🌟 Why DSH-KnowCode?

Traditional AI agent search tools rely on naive lexical search (grep) or flat SQLite FTS tables that lack semantic graph awareness. When working with large codebases (>100k LOC, monorepos, multi-package architectures), agents often:

• Hallucinate function/method signatures or call arguments.
• Miss transitive ripple effects when renaming or modifying shared symbols (high regression risk).
• Introduce circular dependencies between modules.
• Forget to run or update affected test suites.
• Struggle to port complex modules to another programming language due to hidden dependencies.

DSH-KnowCode solves this by unifying:

1. Code Graph: Real Tree-sitter WebAssembly (WASM) AST parsing — no fixed language whitelist — extracting classes, functions, methods, interfaces, types, structs, traits, enums and modules with qualified names, import trees, call hierarchies, inheritance heritage, and test relationships.
2. Knowledge Graph: Architecture Decision Records (ADRs), READMEs, design documents, and coding standards.
3. Cross-Entity Linking: Automatic bidirectional edges between documentation and code symbols ((:DocSection)-[:DOCUMENTS]->(:Symbol) and (:Rule)-[:GOVERNS]->(:File)).
4. Embedded FalkorDB Engine: High-performance sparse-matrix GraphBLAS engine executing Cypher queries in sub-milliseconds without Docker or cloud dependencies.
5. tgrep-style Architecture: One-shot indexer (knowcode index .) and a persistent daemon (knowcode serve) with a debounced incremental file watcher.

---

🚀 Key Highlights & Comparison

---

🌳 Polyglot Tree-sitter AST Engine — No Language Limits

The code graph is built on a real Tree-sitter WebAssembly (WASM) parser, not regex heuristics. There is no fixed language whitelist: the engine ships prebuilt grammars for the most common languages, loads the rest on demand, and accepts any custom Tree-sitter grammar you provide.

Why it matters:

Bundled languages (loaded automatically)

Each language yields the same graph shape — classes, interfaces, structs, traits, enums, modules, functions, methods, qualified names (Namespace.Class.method), inherited signatures, complete startLine/endLine bodies, import edges, and call edges.

Adding a language the engine does not ship

Nothing to compile. Drop a .wasm grammar into any of these locations, and it is picked up automatically:

You can also register one programmatically:

import { TreeSitterEngine } from 'dsh-knowcode/lib/parser/tree-sitter.js';

// Load a grammar by file path or Buffer, and claim extensions for it
await TreeSitterEngine.registerGrammar('haskell', '/grammars/tree-sitter-haskell.wasm', ['.hs', '.lhs']);
TreeSitterEngine.registerExtension('.hbs', 'handlebars');

// Force-load ahead of time (optional — parsing also loads on demand)
await TreeSitterEngine.ensureLanguage('haskell');

A grammar that fails to load (version mismatch, corrupt file) is reported as a warning and skipped — it never aborts an indexing run. Files for that language fall back to the built-in generic declaration scan instead of the AST walker.

---

📦 Installation & Quickstart

Prerequisites

Where does the knowcode command come from?

There is no separate binary to download. knowcode is the CLI entry point shipped inside this package and declared in its package.json:

"bin": { "knowcode": "./bin/knowcode.js" }

Whenever the package is installed or linked, npm/pnpm expose that file as a knowcode symlink inside node_modules/.bin/. The file itself is a plain Node.js script (#!/usr/bin/env node), so it runs anywhere the runtime dependencies are installed.

Pick whichever option below fits your situation.

Option 1 — Run from a clone (no install step)

git clone git@github.com:huuthuan-nguyen/dsh-knowcode.git
cd dsh-knowcode
pnpm install            # runtime deps: commander, falkordb, chokidar, fast-glob, ignore, web-tree-sitter, tree-sitter-wasms
./bin/knowcode.js index .

node bin/knowcode.js index . behaves identically if you prefer to be explicit. The compiled lib/ directory is committed, so no build is required.

After editing anything under src/, rebuild before using the CLI — bin/knowcode.js and the whole CLI import from ../lib/:

pnpm run build

Option 2 — npm link for a global knowcode command

Best for local development, so knowcode works from any directory:

cd dsh-knowcode
pnpm install && pnpm run build
npm link
knowcode index .

npm link reads the bin field and symlinks knowcode into the global bin directory (shown by npm prefix -g). To undo it:

npm unlink -g dsh-knowcode

Option 3 — Install into a DeepSeek Harness profile

Installs the published package into ~/.dsh/profiles/<profile>/node_modules/ and registers it with the harness in one step:

dsh plugin add --profile web dsh-knowcode

The CLI becomes available inside that profile as well:

~/.dsh/profiles/web/node_modules/.bin/knowcode index .

Working on the plugin itself? Point the profile at your checkout instead, so the harness loads your build:

dsh plugin add --profile web link:/absolute/path/to/dsh-knowcode

Prefer configuring the profile by hand? Use the bundle patch shown under DeepSeek Harness Plugin Setup below, then restart the harness.

Option 4 — Install from npm

Published on the public registry as dsh-knowcode, so no clone is needed:

# Try it without installing anything
npx dsh-knowcode index .
npx dsh-knowcode serve .

# …or install the CLI globally
npm install -g dsh-knowcode
knowcode index .

# …or add it to a project
pnpm add dsh-knowcode
pnpm exec knowcode index .

The package bundles the embedded FalkorDB engine for macOS (Apple Silicon) and Linux x64 — ~35 MB compressed, 92.8 MB installed. On a platform without bundled binaries, point FALKORDB_URL at an external instance; see Platform Support & Execution Guide below.

Verify the installation

knowcode --version     # prints the package version
knowcode --help        # lists: index, serve, status, query, stop

Then build a graph for your repository and start the daemon:

knowcode index .                # one-shot index of code + docs
knowcode serve .                # background daemon + live file watcher
knowcode serve . --trace        # …with tgrep-style [trace] diagnostics
knowcode status .               # health, file counts and daemon state

See the CLI Usage section below for the full command reference, and Platform Support & Execution Guide for per-operating-system notes (including Windows/WSL2 and Linux ARM64).

---

🧰 The 25 Agent Tools

Every tool is engineered for LLM Function Calling and Semantic Intent Matching on large codebases:

🧭 1. Architectural Exploration & Orientation

• code_get_architecture_overview (alias: code_explore)

  • Purpose: PRIMARY orientation tool. Queries the FalkorDB code graph to return top-level entry points (exported symbols with 0 internal callers), central hub symbols (ranked by incoming call in-degree / PageRank), and language breakdown without flooding the LLM context window with raw code.
  • When to use: First step when onboarding a new task or exploring unfamiliar subsystems.

• code_get_symbol_definition_and_signature (alias: code_symbol_definition)

  • Purpose: Retrieves the exact AST definition, complete type signature, parameter list, return type, docstring, file path, and start/end line numbers of any function, method, class, struct, or interface.
  • When to use: Eliminates signature hallucinations and argument guessing during implementation or interface conformance.

💥 2. Safe Refactoring & Impact Analysis

• code_analyze_refactor_blast_radius (alias: code_blast_radius)

  • Purpose: CRITICAL SAFE REFACTORING TOOL. Performs transitive graph traversal up to $N$ hops to discover all indirect callers, computes a quantitative risk assessment score (Low/Medium/High/Critical), identifies all affected files, and lists automated test files covering the affected paths.
  • When to use: ALWAYS run before modifying, renaming, or deleting any shared function, class method, or exported API.

• code_find_function_callers (alias: code_callers, code_function_callers)

  • Purpose: Finds all direct invocation sites calling a specific function or class method across the entire codebase. Returns caller names, qualified caller identifiers, file paths, and exact line numbers.
  • When to use: Updating every invocation site when modifying function parameters, argument orders, or return types.

• code_find_function_callees (alias: code_callees, code_function_callees)

  • Purpose: Finds all subroutines, helper functions, and methods called directly by a specific function or method (downward execution trace).
  • When to use: Inspecting dependencies, sub-calls, and error-checking branches to understand implementation logic and preconditions before modifying a function.

• code_detect_circular_dependencies (alias: code_detect_cycles)

  • Purpose: Detects circular import or call dependency loops between files, packages, and modules using FalkorDB cycle traversal.
  • When to use: Modularizing monolithic codebases, breaking tight coupling, or preparing for language ports (e.g. Go and Rust strictly forbid circular package imports).

• code_find_affected_test_files (alias: code_affected_tests)

  • Purpose: Discovers all automated unit and integration test files that cover or import the specified source files. Uses both graph import dependencies and naming conventions (*.test.ts, test.go, test.py).
  • When to use: Verifying zero regressions after completing code edits or bug fixes.

• code_find_similar_duplicate_functions (alias: code_find_duplicates, code_code_clones)

  • Purpose: SEMANTIC & STRUCTURAL CODE CLONE HUNTER. Detects duplicate or near-duplicate functions across the codebase (Type-1 exact clones and Type-2 variable-renamed clones) using normalized AST token stream fingerprinting. Uncovers copy-pasted "dirty code" where logic and control flow are identical but variable names differ, proposing unified abstractions to eliminate technical debt.
  • When to use: Codebase deduplication, technical debt cleanup, and refactoring shared subroutines.

🔄 3. Cross-Language & Paradigm Porting

• code_extract_symbol_porting_contract (alias: code_porting_contract)

  • Purpose: CROSS-LANGUAGE PORTING ACCELERATOR. Extracts the complete language-agnostic interface blueprint of a class, struct, or module: exported signatures, member fields, enclosed methods, external callee dependencies, governing ADR architectural rules, and test suites.
  • When to use: Porting code from one language to another (e.g., Python to Go, TypeScript to Rust) with 100% semantic fidelity.

• code_generate_cross_paradigm_porting_blueprint (alias: code_oop_to_rust, code_port_to_rust)

  • Purpose: OOP-TO-RUST/GO SPECIALIZED ACCELERATOR. Flattens complex OOP class inheritance hierarchies into traits and structs, transforms runtime exceptions (throws Exception) into idiomatic algebraic Result<T, ErrorEnum> types, and provides explicit borrow checker ownership guidelines (avoiding circular Rc/RefCell pitfalls).
  • When to use: Porting Java/C#/C++ object-oriented modules to Rust or Go.

• code_extract_third_party_usage_slice (alias: code_library_slice, code_slim_polyfill)

  • Purpose: ZERO-DEPENDENCY SLIM POLYFILL ACCELERATOR. Identifies the exact subset of a 3rd-party library actually invoked by the codebase. Eliminates the 95% unused library surface and outputs a minimal functional specification and method contract so an AI Agent or developer can re-implement the necessary features from scratch in the target language without bloated external dependencies.
  • When to use: Migrating code when the target language lacks an equivalent 3rd-party library.

📚 4. Bidirectional Spec 🔁 Code Traceability & Knowledge

• spec_find_code_flow_for_feature (alias: spec_to_code_flow, feature_code_flow, code_feature_flow)

  • Purpose: BIDIRECTIONAL TRACEABILITY (Spec ➔ Code Flow). Discovers all functions, classes, and downstream call-flows in the codebase that implement a feature specified in *.md documentation, PRD, or architecture specs. Traverses execution flow from entry points to leaf services and generates an ASCII / Mermaid execution diagram.
  • When to use: Onboarding a feature, verifying whether a specification in *.md has been fully implemented in code, or locating the entire execution path of a user story.

• code_find_spec_features_for_symbol (alias: code_to_spec_features, symbol_feature_specs, feature_for_symbol)

  • Purpose: BIDIRECTIONAL TRACEABILITY (Code ➔ Feature Specs). Identifies all features, specifications in *.md, PRD sections, and architectural rules that a specific function, method, or class belongs to or serves. Traces both direct documentation links and upstream caller execution paths.
  • When to use: Answering "Why does this function exist? What business features or specs depend on this class?" before refactoring or removing a piece of code.

• knowledge_search_documentation_and_rules (alias: knowledge_search)

  • Purpose: Searches across project documentation, Architecture Decision Records (ADRs), specifications, and coding standards. Returns matched sections with priority levels (MUST / SHOULD / AVOID) and automatic cross-links to related code symbols in the graph.
  • When to use: Checking existing architectural patterns or requirements before introducing new abstractions.

• knowledge_get_document_content_and_rules (alias: knowledge_doc)

  • Purpose: Retrieves the full content, heading hierarchy, and architectural rules for a specific documentation file or ADR title.
  • When to use: Understanding why an architectural decision was made (the "Why") before refactoring existing code patterns.

🗄️ 5. Polyglot Contracts & Storage Traceability

• schema_map_contract_to_storage (alias: schema_map_contract, contract_to_db, map_contract_to_storage)

  • Purpose: POLYGLOT CONTRACT-TO-STORAGE ALIGNMENT. Maps any external data contract (XML XSD, JSON OpenAPI/Swagger, gRPC Protobuf) to polyglot storage backends across 7 database families (SQL, MongoDB, Redis, Elasticsearch, Vector DB, TSDB, Graph DB). Produces a field-level mapping matrix, detects type discrepancies (e.g. numeric overflow, BSON ObjectId vs UUID, dense vector dimensions), and flags unmapped/orphan attributes.
  • When to use: Verifying end-to-end data lineage from API contracts to storage, discovering unpersisted fields, or validating type safety across microservice boundaries.

• schema_analyze_storage_migration_impact (alias: schema_migration_impact, db_migration_blast_radius)

  • Purpose: POLYGLOT STORAGE MIGRATION BLAST RADIUS. Analyzes the breaking impact of altering, dropping, or renaming an attribute in SQL tables, MongoDB collections, Elasticsearch indices, or Vector DB collections. Detects all affected external contracts (XML/JSON/gRPC), application DAOs/queries, and mapped test suites.
  • When to use: Running schema migrations, database refactorings, or dropping columns to prevent breaking mobile/web clients or partner integrations.

🔍 6. Advanced Call Path, Architecture & Search

• code_find_call_path_between_symbols (alias: code_call_path, code_trace_call_path)

  • Purpose: Traces the shortest call invocation path between two functions or methods across the entire codebase graph (up to 12 hops). Traces multi-hop execution flow from entry points to downstream services, helping verify architectural layering, security boundaries, and dataflow paths.
  • When to use: Verifying if an API route reaches a critical downstream function (e.g. chargePayment or deleteUser) and observing all intermediate transit points.

• code_find_implementations_and_subtypes (alias: code_subtypes, code_implementations)

  • Purpose: Finds all subclasses, structs, and classes that extend or implement a given interface, abstract class, or base class.
  • When to use: Exploring polymorphism, implementing dependency injection bindings, or writing mock implementations for unit testing.

• code_search_symbols_by_pattern (alias: code_search_symbols)

  • Purpose: Searches for symbols across the codebase by name pattern, case-insensitive substring, or keyword.
  • When to use: Discovering exact qualified symbol names when you only recall partial keywords (e.g. "Token", "Auth", "Payment").

• code_find_unused_dead_symbols (alias: code_dead_code, code_unused_symbols)

  • Purpose: Identifies unreferenced internal/private symbols with 0 incoming calls in the codebase graph.
  • When to use: Performing technical debt cleanups and safely pruning obsolete dead code.

• code_analyze_git_diff_semantic_impact (alias: code_git_diff_impact, code_audit_git_diff)

  • Purpose: ONE-CLICK REGRESSION AUDIT. Analyzes uncommitted git working tree changes (or changes against a base commit/branch), maps changed line ranges to AST symbols, computes transitive callers at risk, and identifies all automated test suites to run before commit or PR creation.
  • When to use: Pre-commit safety check to verify zero regressions before concluding a coding task.

⚡ 7. Diagnostics & Power Queries

• knowcode_check_index_health_and_stats (alias: knowcode_status)

  • Purpose: Checks graph health, number of indexed files/symbols/calls/docs, daemon freshness, and memory statistics.
  • When to use: Run once per session to confirm index freshness.

• knowcode_trigger_incremental_reindex (alias: knowcode_sync)

  • Purpose: Triggers an on-demand incremental re-index of any modified or newly added files across the workspace.
  • When to use: After large batch edits to synchronize the graph with disk.

• knowcode_execute_custom_cypher_query (alias: knowcode_cypher)

  • Purpose: Direct Cypher query escape hatch against FalkorDB.
  • When to use: Advanced multi-hop graph queries (e.g., finding classes implementing interface X that do not call method Y).

---

🛠 CLI Usage (Microsoft tgrep-style)

dsh-knowcode ships with the knowcode executable CLI for terminal usage and CI/CD pipelines.

Not sure you have the knowcode command yet? It is not a separate download — see Installation & Quickstart above for the four ways to obtain it. Quick check: knowcode --version.

Throughout this section, knowcode … can always be replaced by ./bin/knowcode.js … when running from a clone.

Which command do I need?

serve indexes the workspace by itself — index is optional. There is no need to index before serving.

On startup, and before it announces readiness, serve reconciles the graph with the filesystem: