codeknit — static code structure extraction

codeknit parses source code and produces a structural map of symbols and relationships designed for LLM consumption or structured tool integration.

Important: choosing the right output mode

Default to directory-flat (no flag needed) unless you are certain the input is a single file or just a few files. Most projects have more files than you expect, and inline mode dumps everything to stdout which can overwhelm context windows and become unreadable. When in doubt, use the default — it writes chunked .skt files to ./skeleton/ that you can read selectively.

Only use --output-mode inline when:

• The input is a single file
• You explicitly need stdout output for piping
• You have confirmed the project has very few source files (< 5)

Quick start

# Default: chunked .skt files in ./skeleton/ (best for most projects)
codeknit parse ./src

# Re-run on the same project (cleans previous output)
codeknit parse ./src --clean

# Single file to stdout
codeknit parse ./src/main.go --output-mode inline

# Machine-readable JSON to stdout
codeknit parse ./src --output-mode inline --format json --edges

# Custom output directory
codeknit parse ./src ./output

# Mirror source tree structure
codeknit parse ./src --output-mode directory-tree

Commands

codeknit parse <input-path> [output-dir]

The output directory defaults to ./skeleton for directory-flat and directory-tree modes. Pass a second argument to override it. In inline mode no directory is created. The default output format is .skt; pass --format json for machine-readable JSON. In directory modes, JSON is written as codeknit.json.

If the output directory already contains .skt files from a previous run, codeknit will refuse to write to avoid mixing stale and fresh output. Pass --clean to remove them automatically.

Choosing an output mode

Rules of thumb:

• When unsure about project size → use the default (directory-flat), never inline
• Analyzing a single file → inline is fine
• Anything beyond a few files → directory-flat or directory-tree
• When you want to look up a specific file's structure quickly → directory-tree
• When another tool needs structured data → --format json
• Add --minify on any mode to compress repeated tokens via a dict.skt dictionary
• By default the [edges] section is omitted to save tokens; pass --edges when you need relationship data (contains, calls, inherits, etc.)
• Add --clean when re-running on the same output directory
• Omit the output directory to use the default ./skeleton; pass a path to override

Reading output

The default .skt output format has sections: [symbols], [edges], optionally [errors] and [dict]. JSON output contains top-level files, symbols, optional edges, and optional errors arrays.

See OUTPUT-FORMAT.md for the complete format reference with examples.

Important: use codeknit output for analysis, not source code

When performing structural analysis (dependency mapping, refactoring planning, architecture review, etc.), always read codeknit output instead of the raw source code. The .skt skeleton files or JSON output contain the extracted structural information — symbols, relationships, line spans — in a compact format designed for exactly this purpose. Reading source files directly for structural questions wastes context and is less reliable.

Only read the actual source code when you need to inspect or modify implementation details (e.g. fixing a bug, reviewing logic, writing new code). For anything structural — "what calls what", "where is this class used", "show me the dependency graph" — codeknit output is the right tool.

Graph analysis

Use codeknit graph analyze to run structural graph algorithms and get an LLM-readable report of code quality issues (cyclic dependencies, hub symbols, dead code, god classes, bottlenecks, and more).

# Run structural analysis
codeknit graph analyze ./src

# Custom output and thresholds
codeknit graph analyze ./src -o analysis.skt --fan-threshold 15

# Show more results
codeknit graph analyze ./src --top-n 50

The output is a .skt file — read it the same way you read parse output.

Workflow

1. Run codeknit parse ./src to extract structure into ./skeleton/
2. Read the .skt files selectively — start with the ones relevant to your task (do not read source files for structural questions)
3. Read [symbols] to see what exists and where (file, line span)
4. Read [edges] to trace relationships — calls, inheritance, containment
5. Use line spans (e.g. L5-L20) to locate exact source code only when you need to inspect or modify implementation
6. For deeper structural insights, run codeknit graph analyze ./src and read the resulting .skt report
7. For re-runs, add --clean to remove previous output: codeknit parse ./src --clean
8. For single-file quick inspection only, use codeknit parse ./file.ts --output-mode inline
9. For scripts or integrations, use codeknit parse ./src --output-mode inline --format json --edges