codeknow

codeknow [path] [options]codeknow command [args] [options]

codeknow builds a queryable knowledge graph from a source tree. It walks the project with tree-sitter, extracts symbols (functions, classes, modules) and relationships (imports, calls, inheritance), and stores them as a NetworkX directed graph. Language detection is automatic; the default install covers Python, JavaScript/TypeScript, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia, Verilog, Fortran, Bash, Groovy, and JSON, with extras for SQL, Terraform, Pascal, OCaml, Common Lisp, and others.Running codeknow . (or codeknow extract .) writes codegraph-out/graph.json, an interactive graph.html, and GRAPH_REPORT.md. Core analysis — debt, drift, onboard, impact, test-impact, security, owners, refactor-plan, simulate, discover — reads that graph and does not need an API key. query, community labeling, and semantic document extraction are optional LLM passes (OpenAI, Anthropic, Gemini, Ollama, and custom OpenAI-compatible endpoints).The published console script is codeknow; the Python package, default output directory, git-hook helpers, and --help banner still use the older name codegraph.

-h, --help, -?

Print the full command list and exit.

Print the package version. Help text still labels the binary as codegraph.

Emit machine-readable JSON on analysis commands that support it (debt, impact, security, owners, god-nodes, diagnose, and others).

Path to graph.json (default codegraph-out/graph.json, or $CODEGRAPH_OUT/graph.json).

CODEGRAPH_OUT

Override the output directory name or path (default codegraph-out). Read once at process start; set it before invoking the CLI.

Set to 1/true/yes to force a full re-scan, same as --force on extract and update.

Project ignore file. Honoured even when --no-gitignore skips .gitignore.

Default artifact directory: graph.json, graph.html, GRAPH_REPORT.md, drift baselines, onboarding, and memory/reflections. Analysis commands look here unless --graph is given.

Cross-repo global graph (global-graph.json) and cloned repos used by clone / global.

path

A filesystem path as the first argument is treated as extract path. codeknow . is the usual first run.

Headless full extraction: tree-sitter AST parse, optional LLM semantic pass, cluster, and write codegraph-out/. --code-only skips docs, papers, and images and needs no API key. --no-cluster writes raw extraction only. --no-gitignore ignores .gitignore (still honours .codegraphignore). --force (or CODEGRAPH_FORCE=1) full re-scan. --out DIR writes DIR/codegraph-out/. --postgres DSN and --cargo add database schema or Cargo crate edges. --global merges into the cross-repo graph.

Re-extract changed files and update the graph without an LLM. --force overwrites even if the rebuild has fewer nodes.

Composite health score 0–100 with letter grade. Sub-metrics: god-node concentration, cross-community coupling, import cycles, community cohesion, dead code. --threshold N exits 1 when the score is below N. --score-only prints just the number.

Save the current graph as a named baseline (--name NAME).

Detect structural changes against the last (or named) baseline.

List saved baselines.

Git-aware architectural changelog. --since 2w, --between b1 b2, --ref REF, --output PATH.

Write ONBOARDING.md next to the graph (betweenness + communities, no LLM). --top N, --stdout.

Blast-radius analysis with risk assessment. --depth N (default 3).

Reverse traversal of nodes impacted by a change. --relation R (repeatable), --depth N (default 2).

Map files to affected tests (HIGH/MEDIUM/LOW). --changed uses git, --all lists every mapping. Pipe to xargs pytest.

Attack-surface analysis: source-to-sink path tracing. --markdown for Markdown output.

Git-blame overlay: knowledge silos, bus factor, orphaned communities. --codeowners generates a CODEOWNERS file. --orphan-days N (default 90).

Dependency-aware refactor plan with blast radius and a topologically sorted order.

Cascade analysis of deleting a node.

Simulate merging two modules.

Simulate extracting nodes into a new module.

Latent connections, bridges, and capability clusters.

Identify product features from code structure.

Match the graph against a set of architecture patterns.

Highest-degree nodes (architectural hubs). --top N (default 10).

Plain-language explanation of a node and its neighbors.

Shortest path between two nodes.

Natural-language query over the graph (requires an LLM extra). --dfs, --budget N, --context C (repeatable).

Keyboard-driven terminal navigator (stdlib + ANSI, no extra packages).

Live architecture dashboard at http://127.0.0.1:8787. --port N.

Collapsible HTML dependency tree (codegraph-out/GRAPH_TREE.html).

html, callflow-html, obsidian, wiki, svg, graphml, neo4j, falkordb. Neo4j/FalkorDB can --push to a live database.

Copy the agent skill into a coding-agent config (claude, cursor, gemini, codex, vscode, kilo, kiro, and others). codeknow-mcp is a separate entry point from pip install "codeknow[mcp]".

Merge a project graph into ~/.codegraph/global-graph.json. global list, global remove, global path.

Rebuild the graph when files change (needs the watch extra).

Requires Python 3.10+. Install from PyPI (pip install codeknow); distro packages may not exist.Most analysis subcommands exit with an error until a graph has been built. query and LLM community labeling need an extra and an API key.Help text, default paths, and the companion MCP binary still say codegraph / codeknow-mcp. SVG export, Neo4j, FalkorDB, PDF/Office ingest, video transcription, and the file watcher are optional extras, not part of the base wheel.Very large graphs can skip HTML generation with --no-viz. --code-only is the CI-friendly path: no LLM, code files only.

codeknow is written in Python by Alex Salsali and released under the MIT license. Version 1.0.0 was published on 31 August 2026 (tree-sitter extractors, HTML visualization, simulation and discovery engines). 1.1.0 followed on 1 September 2026 with debt, drift, changelog, onboard, test-impact, owners, refactor-plan, security, tui, and dashboard. The library package remains codegraph.

ast-grep(1), semgrep(1), scc(1), ctags(1), cscope(1)

Source code