# codeknit-parse

Extracts functions, classes, and dependencies from source code in twelve languages into compact files for code review and refactoring.

Skill by Amazon Web Services. Category: Code quality.

## Install

Project (for this project only):

```sh
npx skills add awslabs/codeknit --skill codeknit-parse
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add awslabs/codeknit --skill codeknit-parse -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 1. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/awslabs/codeknit/codeknit-parse)

## Source

[Open the source](https://github.com/awslabs/codeknit/tree/HEAD/skills/codeknit-parse). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: codeknit-parse
description: "Extracts code structure (functions, classes, methods, variables) and relationships (calls, inheritance, containment) from source files into compact .skt or JSON output using codeknit. Use when analyzing a codebase, understanding code structure, mapping dependencies, or preparing context for code review and refactoring. Supports C, C++, C#, Go, Java, JavaScript, PHP, Python, Ruby, Rust, Scala, and TypeScript."
---

# 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

```bash
# 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 replace them only after successful generation. Failed generation preserves the previous output.

| Flag             | Default          | Description                                                           |
| ---------------- | ---------------- | --------------------------------------------------------------------- |
| `--output-mode`  | `directory-flat` | `inline`, `directory-flat`, or `directory-tree`                       |
| `--format`       | `skt`            | Output format: `skt` or `json`                                        |
| `--max-lines`    | `500`            | Tree source-chunk limit (minimum 3); flat keeps source blocks intact  |
| `--collect-test` | `false`          | Include test files in analysis                                        |
| `--minify`       | `false`          | Dictionary-based compression of repeated tokens                       |
| `--edges`        | `false`          | Include the [edges] section in output (off by default to save tokens) |
| `--clean`        | `false`          | Replace prior generated output after successful generation            |
| `--workers`      | `NumCPU`         | Max concurrent parsing goroutines                                     |
| `--verbose`      | `false`          | Print progress and timing info                                        |

## Choosing an output mode

| Mode             | Best for                                | Output location                                                                     |
| ---------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
| `inline`         | A single file, piping to another tool   | Dumps everything to stdout — only use for single files or very small projects       |
| `directory-flat` | Most projects (default, recommended)    | `./skeleton/map_001.skt`, `map_002.skt`, ... — chunked, read only what you need     |
| `directory-tree` | Navigating output alongside source code | `./skeleton/<source name with extension>.skt`; split names use `<source>_partN.skt` |

| Format | Best for                           | Output                                                    |
| ------ | ---------------------------------- | --------------------------------------------------------- |
| `skt`  | LLM context and human inspection   | `.skt` files or stdout                                    |
| `json` | Scripts and structured integration | `codeknit.json` in directory modes, or stdout in `inline` |

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.

Edges marked `[unresolved]` or `[ambiguous]` are uncertain relationships, not confirmed dependencies. Candidate IDs are possible targets. File/include metadata symbols provide readable endpoints without proving that a header was resolved. Graph analysis excludes uncertain edges and reports their counts; the HTML viewer currently shows those counts without drawing uncertain links.

See [OUTPUT-FORMAT.md](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).

```bash
# 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
```

| Flag                      | Default                         | Description                                          |
| ------------------------- | ------------------------------- | ---------------------------------------------------- |
| `-o`, `--output`          | `./skeleton/graph_analysis.skt` | Output `.skt` file path                              |
| `--collect-test`          | `false`                         | Include test files in analysis                       |
| `--workers`               | `NumCPU`                        | Max concurrent parsing goroutines                    |
| `--verbose`               | `false`                         | Print progress and timing info                       |
| `--fan-threshold`         | `10`                            | Min fan-in or fan-out to flag a hub symbol           |
| `--god-threshold`         | `15`                            | Min contains-edge count to flag a god class/function |
| `--max-inheritance-depth` | `5`                             | Flag inheritance chains deeper than this             |
| `--top-n`                 | `30`                            | Cap ranked output sections; 0 = no limit             |
| `--betweenness-threshold` | `0.001`                         | Min betweenness centrality value to report           |
| `--propagation-cutoff`    | `0.05`                          | Min probability to continue change propagation       |

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`

## Scan reliability

All source commands support repeatable `--include GLOB` / `--exclude GLOB`, `--max-file-size BYTES` (10 MiB default, `0` unlimited), and `--strict`. Quote globs and make them relative to the input root. Includes do not override ignore rules or test filtering. Symlinks are skipped and reported. Inspect stderr and JSON `errors` / SKT `[errors]`; use `--strict` when incomplete analysis must fail before writing output. See `docs/reference/analysis-reliability.md` for the maintained contract.
````

- Previous: [wordpress-creator](https://syn4pse.dev/terminal/wordpress-creator.md)
- Next: [email-audit](https://syn4pse.dev/terminal/bird-email-audit.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
