knodin

For an approval-gated, evidence-first way to declare a multi-repository system, use the sanitized assistant prompt.

knodin init installs focused knodin-* assistant skills for detected Codex, Claude, and Gemini clients. Use knodin skills list|install|remove|doctor to inspect or manage them explicitly; CLI-only scope installs none.

Local code intelligence that remembers how your code connects—and shows what may move before you change it.

knodin builds and continuously refreshes a local graph of an existing codebase. Engineers and coding agents use it to understand unfamiliar code, find affected dependencies, review changes, search by meaning or name, and assemble bounded source context without sending source code to a hosted service.

It ships as one CLI and one operation-routed MCP tool. There is no account, hosted index, authentication flow, source egress, or separate database service.

Why use knodin?

A code change usually starts with repeated manual work: find the definition, read its callers, inspect dependencies, locate tests, understand the diff, and assemble enough source for the next decision. knodin composes those steps over one persistent local graph.

• Understand before editing: resolved symbols, verbatim source, call paths, architecture communities, and execution flows.
• See potential impact: upstream and downstream relationships, affected tests, changed symbols, review risk, and explicit ambiguity.
• Give agents better context: hybrid search and deterministic source packs with hard line, byte, and token budgets.
• Keep evidence trustworthy: source locations, graph freshness, lifecycle health, repair commands, and truthful truncation metadata.
• Adopt locally: initialize the checkout you already have and use the CLI or connect one MCP gateway.

The practical value is less manual context assembly and fewer dependencies missed during review, with no hosted-service or source-egress overhead. Fewer agent round trips are an intended payoff; the narrow C93 replay measured no round-trip difference, so knodin does not claim a general productivity effect.

Four checked answers define the product rather than a feature-count claim:

• Value: less manual context assembly and fewer missed dependencies. C93 records the paired task method; C100 narrows one missed-dependency result from a Salesforce class file to the exact Flow-invoked Apex method.
• ROI: the intended mechanism is fewer corrective agent round trips without hosted-service, authentication, or source-egress overhead. C93's accepted two-task replay measured no round-trip benefit (both arms required one correction), so this remains a product hypothesis rather than a measured productivity claim. Billed cost and unobserved tokens remain unknown.
• Tomorrow: run knodin init, check knodin status, then use the local CLI or single MCP gateway against the checkout already on disk.
• Secret sauce: stable identity, exact source evidence, explicit freshness, and truthful budgets compose behind one compact local tool.

The checked behavioral contract release-gates that composition. C101 binds the bounded resource-reachability, TypeScript DI, and Salesforce Flow-to-Apex evidence to the retained one-process semantic design. It rejects stale, truncated, ambiguous, or omission-only output when a mutation tries to promote it into a complete or exact claim. These are fixture-scoped guarantees with recorded limits, not universal superiority.

How it compares

Code-intelligence tools often specialize in one part of the workflow. knodin combines navigation, impact analysis, architecture, retrieval, and bounded context over one locally persisted index.

| Job | Typical specialized tools | knodin | |---|---|---| | Symbol navigation | CodeGraph, Serena, Sourcegraph | Ambiguity-safe definitions, callers, callees, paths, bounded Inversify/tsyringe DI edges, and verbatim source | | Change impact and review | code-review-graph, Greptile, Graphify | Diff-aware review, impact traversal, tests, risks, and PR triage | | Architecture mapping | Graphify, GitNexus | Communities, hubs, boundaries, flows, wiki, and local visualization | | Search and context assembly | Aider repo map, Repomix, semantic search tools | Hybrid search, bounded source packs, and recoverable diagnostic compression | | Bounded resource and framework relationships | Code-Graph-RAG and framework-aware analyzers | Literal TS/JS resource paths, declared Inversify/tsyringe wiring, and one exact Salesforce Flow-to-Apex boundary, each with explicit omissions | | Deployment | Hosted services or separate local tools | One local process, SQLite graph, CLI, and one MCP gateway |

Measured results

On the checked-in Token Optimizer replay, knodin passed the shared correctness oracle for all five safe structural workflows while using fewer real tokens and running faster at warm p50 and p95 in every case:

| Workflow | Tokens (knodin vs competitor) | Warm p50 (knodin vs competitor) | Result | |---|---:|---:|---:| | File outline | 56 vs 64 | 0.203 vs 0.478 ms | 2.4× faster | | Exact symbol source | 33 vs 37 | 0.258 vs 0.419 ms | 1.6× faster | | Symbol search | 76 vs 84 | 0.227 vs 1.112 ms | 4.9× faster | | Batch outline | 331 vs 377 | 0.184 vs 1.387 ms | 7.5× faster | | Project overview | 14 vs 127 | 0.135 vs 0.589 ms | 4.4× faster, 89% fewer tokens |

Across the broader checked-in competitive replay, knodin was faster in 488 of 713 paired cases (68.4%). It did not win every workload: competitors won 225 cases, including the aggregate warm-latency result for several packing and memory tools. Cold startup is also slower in the Token Optimizer comparison.

These are fixture-scoped measurements, not estimates. See the replay synthesis, scorecard, and raw benchmark artifacts for methods, pinned revisions, correctness oracles, and limitations.

This table describes product scope, not a universal superiority claim. Product capabilities overlap, and static analysis has limits in dynamically wired or framework-driven code. The comparison notes separate checked-in measurements, vendor claims, setup blockers, and known gaps. The competitive roadmap records remaining limitations.

Install

knodin requires Node.js 24 or newer.

npm install --global --ignore-scripts knodin

Initialize an existing repository:

cd /path/to/repository
knodin init
knodin status --deep

knodin init builds the local graph, installs lifecycle hooks, and can configure detected coding agents. Choose an integration scope explicitly when needed:

knodin init --scope personal   # local configuration; keeps the repo clean
knodin init --scope team       # commit-ready shared agent configuration
knodin init --scope cli-only   # graph and CLI without agent configuration

See the installation guide for package-manager details, managed registries, upgrades, and uninstall instructions.

If one application spans several repositories—including repositories you can pull locally but cannot change upstream—follow the local multi-repository setup guide. It covers personal-only initialization, automatic refresh after pulls, hook coexistence, portfolio search, and optional system composition.

First workflow

Start broad, inspect the likely change surface, then review the actual diff:

# Orient on an unfamiliar checkout
knodin context "understand this checkout"

# Explain a symbol with source and relationships
knodin explain createServer

# Find what depends on it
knodin query impact createServer --direction upstream

# Review current changes
knodin review --scope all

For discovery and bounded context:

knodin search "authentication middleware"
knodin map
knodin pack createServer --max-tokens 4000

For a task that needs an implementation and its dependencies:

knodin context "find code that persists an order" --implementations --json
knodin context "rename persist" --symbol persist --file src/storage.ts --json
knodin evidence expand --files src/storage.ts --items 100 --json

Discovery returns candidates for you to select; investigation collects source, callers, importers, tests, and impact for the selected identity. Evidence bundles page exact source and issue reusable per-file receipts after complete delivery. Ambiguity, incomplete coverage, and budget limits stay visible. See the CLI guide and evidence protocol.

If freshness or lifecycle checks fail:

knodin status --deep
knodin repair

What it does

| Command | Purpose | |---|---| | knodin context | Compact repository orientation and next-operation hint | | knodin explain <symbol> | Source, identity, typed callers/callees, static-analysis omissions, and blast radius | | knodin review | Itemized graph impact, test gaps, centrality, and bounded Git-history evidence | | knodin query … | Impact, paths, callers, callees, tests, flows, and structured graph queries | | knodin search <query> | Explainable structural-first search with a bounded local embedding fallback | | knodin index --scip <file> | Opt in to a bounded local SCIP snapshot while preserving native and LSIF facts | | knodin map | Subsystems, communities, hubs, bridges, and boundaries | | knodin pack … | Deterministic source context under hard budgets | | knodin compress … | Bounded diagnostic output with recoverable local detail | | knodin prs | Open-PR triage using the authenticated local gh CLI | | knodin wiki | Static Markdown architecture documentation | | knodin visualize | Self-contained local graph visualization: whole-repository dependency graph or a bounded call flow | | knodin status --deep | Index freshness, health, hooks, and integration status | | knodin repair | Repair or rebuild unhealthy local graph state | | knodin diagnostics … | Preview and archive explicit-allowlist local support evidence | | knodin agent-hooks … | Explicitly install, inspect, or remove optional user-global Claude lifecycle hooks | | knodin telemetry … | Opt into private repository-local adoption evidence and render the local dashboard |

Run knodin --help or read the CLI reference for complete syntax.

MCP

knodin init configures supported agents automatically. A manual MCP configuration uses one local server:

{
  "mcpServers": {
    "knodin": {
      "command": "knodin",
      "args": ["serve"]
    }
  }
}

The gateway exposes one knodin tool whose operation selects context, explain, review, map, search, query, pack, compress, PR, wiki, telemetry, repository, and lifecycle capabilities. See the MCP guide.

Local data and privacy

Each checkout stores its graph and lifecycle state in .knodin/. Shared model files live in the user cache rather than being duplicated per repository. Source and graph data stay local. Telemetry is metadata-only, disabled by default, and never sent by knodin. Optional Claude hooks are installed only by knodin agent-hooks install --client claude; they inject bounded, freshness-aware session orientation and no-op outside initialized repositories. Adoption capture remains a separate opt-in through knodin telemetry enable. Troubleshooting diagnostics are also explicitly enabled, local-only, bounded, and never uploaded automatically.

The optional prs command invokes the user's authenticated gh CLI. Network access may also occur when installing packages, downloading the configured embedding model, or explicitly checking for updates.

Evidence and limitations

knodin reports ambiguity, stale indexes, incomplete language coverage, and budget truncation instead of presenting uncertain results as complete. Its checked-in tests and competitive replays measure narrower correctness, latency, retrieval, and response-size outcomes; they do not establish a universal productivity percentage or superiority over every competing product.

• Status and evidence
• Comparison notes
• Competitive landscape
• Competitive roadmap and limitations
• Systems and relationships
• Command-output compression
• Local troubleshooting diagnostics

Develop

Internal GHES mirror

GitHub SaaS DTS-Productivity-Engineering/knodin is the authoritative review and release repository. knodin/knodin is the Homebrew-tap repository, not a source or release authority. The internal github.docusignhq.com/Enterprise-Apps/knodin repository is a read-only mirror for colleagues who need GHES access; work must not be opened or reviewed there.

After a pull fast-forwards local main, Lefthook automatically fast-forwards the mirror when this maintainer-local remote exists:

git remote add ghes [email protected]:Enterprise-Apps/knodin.git

The hook silently no-ops off main, on CI, or without that remote. It never forces and never breaks the surrounding merge when GHES is unavailable. Run npm run mirror:sync for manual recovery. A divergence is reported for investigation instead of being overwritten.

npm ci
npm run build
npm test
npm run lint
npm run typecheck

License

Apache-2.0