Skip to main content

Knots

A fast multi-language code complexity analyzer built on tree-sitter. Knots measures traditional complexity metrics alongside two AI-specific cost scores — AIRD (AI Reasoning Difficulty) and AICP (AI Context Pressure) — to identify which functions are genuinely expensive to modify with AI assistance.

Features

  • Multiple Complexity Metrics: McCabe, Cognitive, Nesting Depth, SLOC, ABC, Test Scoring
  • AI Cost Metrics: AIRD (reasoning difficulty) and AICP (context pressure) — corpus-validated against 32,205 functions across 6 open-source C codebases
  • Multi-Language: C, C++, Rust, Python, JavaScript, TypeScript, Ada, Go, Java, C#, Kotlin, Swift, PHP, Fortran, Scala, and Lua — same metrics and thresholds across all supported languages
  • Testability Matrix: Categorize functions by complexity and testability
  • Multiple Output Formats: text, SARIF, JSON, NDJSON (find/xargs-composable), CSV
  • CI Threshold Enforcement: exit 1 on any threshold violation; recommended --aird-threshold 85
  • Pre-commit Hook: native integration, no shim scripts required
  • Validated: McCabe matches pmccabe exactly; Cognitive matches Mozilla rust-code-analysis at 1.004× mean ratio (11,365 Rust functions)

Installation

Prebuilt binary from PyPI (no Rust toolchain, installs in seconds):

pipx install knots          # or: uv tool install knots

From crates.io:

cargo install knots

Or from source:

git clone https://github.com/brandon-arrendondo/knots.git
cd knots
cargo build --release

No C compiler or build system required.

Quick Start

# Single file
knots src/main.c

# Recursive directory
knots -r src/

# CI gate — fail if any function has AIRD > 85
knots -r src/ --aird-threshold 85

# Adopt the gate on a legacy codebase: snapshot today, then fail only on regressions
knots -r src/ --aird-threshold 85 --baseline .knots-baseline.json --write-baseline
knots -r src/ --aird-threshold 85 --baseline .knots-baseline.json

# Gate only the functions you actually touched (no new debt in this change)
knots -r src/ --aird-threshold 85 --changed

# SARIF for GitHub Code Scanning
knots -r --format sarif src/ > knots.sarif

# Corpus analysis — one JSON record per function
find . -name "*.c" -o -name "*.rs" | xargs knots --format ndjson > metrics.ndjson

# Testability matrix
knots -m src/main.c

Complexity Indicators

Based on max(McCabe, cognitive):

Range Indicator Meaning
1–10 😊 Good Low complexity, easy to maintain
11–20 😐 Okay Moderate complexity, monitor
21–49 😠 Bad High complexity, consider refactoring
50+ 😢 Critical Urgent refactoring needed

Command-Line Options

knots [OPTIONS] [FILE]...
knots [OPTIONS] --compile-commands <FILE>

Options:
  -r, --recursive                   Recursively process all supported source files in directories
  -v, --verbose                     Show detailed per-function analysis
  -m, --matrix                      Show testability matrix categorization
  --compile-commands <FILE>         Use compile_commands.json to get file list
  --include <FILE>                  Include filter rules from JSON file (whitelist)
  --exclude <FILE>                  Exclude filter rules from JSON file (blacklist)
  --exclude-path <PATTERN>          Exclude files whose path matches this regex (repeatable)
  --format <FORMAT>                 text (default) | sarif | json | ndjson | csv
  --mccabe-threshold <N>            Exit 1 if any function exceeds this McCabe complexity
  --cognitive-threshold <N>         Exit 1 if any function exceeds this cognitive complexity
  --nesting-threshold <N>           Exit 1 if any function exceeds this nesting depth
  --sloc-threshold <N>              Exit 1 if any function exceeds this SLOC count
  --abc-threshold <F>               Exit 1 if any function exceeds this ABC magnitude
  --return-threshold <N>            Exit 1 if any function exceeds this return count
  --aird-threshold <N>              Exit 1 if any function exceeds this AIRD (AI Reasoning Difficulty) score (recommended: 85)
  --aicp-threshold <N>              Exit 1 if any function exceeds this AICP (AI Context Pressure) score
  --external-calls-threshold <N>    Exit 1 if any function exceeds this external call count
  --unreachable-blocks-threshold <N> Exit 1 if any function has more than this many unreachable (dead-code) basic blocks (C/C++/Rust only)
  --report <FILE>                   Write a detailed per-function report to this file (opt-in)
  --baseline <FILE>                 Ratchet mode: gate only on regressions vs. this snapshot (see docs/baseline.rst)
  --write-baseline                  Snapshot current scores to --baseline and exit without gating
  --since <REF>                     Gate only functions overlapping lines changed since this git ref
  --changed                         Gate only functions changed in the working tree (sugar for --since HEAD)
  --explain <METRIC>                Explain a metric (e.g. aird, aicp) and how to lower it, then exit
  --find-duplicates                 Report structurally duplicated functions across the corpus (--recursive only)
  --include-fixture-pairs           Keep tests/pass vs tests/fail fixture pairs in --find-duplicates output (excluded by default)
  --include-trivial-duplicates      Keep small-body, low-repeat groups (getters, one-assert tests) in --find-duplicates output (excluded by default)
  --dump-duplicates <FILE>          Write a JSON snapshot of --find-duplicates results, for later comparison via --diff-duplicates
  --diff-duplicates <BEFORE> <AFTER>  Compare two --dump-duplicates snapshots and summarize resolved/new/shrank/grew groups; exits without needing corpus files
  -j, --jobs <N>                    Parallel analysis threads (0 = auto-detect, 1 = sequential, default: 0)
  -h, --help                        Print help
  -V, --version                     Print version

Documentation

Full documentation is in the docs/ directory (Sphinx/RST):

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

knots-1.14.0.tar.gz (214.6 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

knots-1.14.0-py3-none-win_amd64.whl (4.9 MB view details)

Uploaded Python 3Windows x86-64

knots-1.14.0-py3-none-musllinux_1_2_x86_64.whl (5.4 MB view details)

Uploaded Python 3musllinux: musl 1.2+ x86-64

knots-1.14.0-py3-none-musllinux_1_2_aarch64.whl (5.2 MB view details)

Uploaded Python 3musllinux: musl 1.2+ ARM64

knots-1.14.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.3 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

knots-1.14.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (5.3 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ARM64

knots-1.14.0-py3-none-macosx_11_0_arm64.whl (5.3 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

knots-1.14.0-py3-none-macosx_10_12_x86_64.whl (5.1 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file knots-1.14.0.tar.gz.

File metadata

  • Download URL: knots-1.14.0.tar.gz
  • Upload date:
  • Size: 214.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for knots-1.14.0.tar.gz
Algorithm Hash digest
SHA256 01931869ebd54d978d05337c7d841507979d1f633c3820530e3b7b98ee11b74e
MD5 730786378d976cef1ea468f1f19bd29f
BLAKE2b-256 e3ad4a829fe5b5603bfb5c2904c8800040982a57d7601094be2a6a735f07961f

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.14.0.tar.gz:

Publisher: wheels.yml on brandon-arrendondo/knots

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file knots-1.14.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: knots-1.14.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 4.9 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for knots-1.14.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 2f35d280fe9bd7710b1d4a090a69b6d411aa84c20adb1d138f7565c7a8b11f69
MD5 135e11500866565c7da37574e21f7237
BLAKE2b-256 7769f24ab971ae7dfcfb5f606a34e8857213397b804fdc3fd53fa7ded5bcfd11

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.14.0-py3-none-win_amd64.whl:

Publisher: wheels.yml on brandon-arrendondo/knots

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file knots-1.14.0-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for knots-1.14.0-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 fe85a0ffad4aa420f3cffe92968d98bc7acd8ebbdd1073594d646d20b6e4c538
MD5 fa751634038df25a88a2a71e320f7f8e
BLAKE2b-256 07cc7797377f0936a55605ac2acdc6fb805bba8af8fd2758a9a32a07cb81fbbd

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.14.0-py3-none-musllinux_1_2_x86_64.whl:

Publisher: wheels.yml on brandon-arrendondo/knots

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file knots-1.14.0-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for knots-1.14.0-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 a7aa66f5fbd8ae9dca0f238b1eb9045e309e9b83be2e253d90042895b897b9dc
MD5 33ecc7aa9a98ee05d13c083835857c41
BLAKE2b-256 d21596d53c83fb9806d68a5ea78202047bf7e901179e36bd0d33122373409e1e

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.14.0-py3-none-musllinux_1_2_aarch64.whl:

Publisher: wheels.yml on brandon-arrendondo/knots

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file knots-1.14.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for knots-1.14.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 10b17ac31f779a8742d995db5076692dd8f0c051087f34072ff42b4c7907c777
MD5 300c5929b71ab8ba28881d377a97fdc9
BLAKE2b-256 641a692a8bc95b1c960ada65394f313aace5d08e683bdb3dc01859fdf72d6cc5

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.14.0-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: wheels.yml on brandon-arrendondo/knots

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file knots-1.14.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for knots-1.14.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 bc5f2887ea90f12d349c701635b7bc3da8d1344ed580294394f8fa17415cf6ec
MD5 489aef31f25507bcb5b6ac60622a86ca
BLAKE2b-256 1dc256e7cf5da7ca7d7a7a499a60d0c73fc95680b097f7c591f7f2593ce1a3b7

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.14.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: wheels.yml on brandon-arrendondo/knots

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file knots-1.14.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for knots-1.14.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7241fff4546a525ddd44ad7f960282b95a7046624ba7ef64775a113f964e12fc
MD5 f495db790899c50cb4f8b2d320128d31
BLAKE2b-256 c062f46c13d3be02603a84f43d913ea25928cd331dc54638df6f20cf85f9784e

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.14.0-py3-none-macosx_11_0_arm64.whl:

Publisher: wheels.yml on brandon-arrendondo/knots

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file knots-1.14.0-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for knots-1.14.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 060d7f6415b852b9f07b93537567d412cc7734986b899a2e339101dfb37b59b7
MD5 145ba8a0c549d0b86fc17b7ced841814
BLAKE2b-256 658f3128be922684171feb84213456513e6246285430ff80cf14c985f944aba0

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.14.0-py3-none-macosx_10_12_x86_64.whl:

Publisher: wheels.yml on brandon-arrendondo/knots

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.16.0

8 files

1.15.1

8 files

1.15.0

8 files

This release

1.14.0 This release

8 files

1.13.1

8 files

1.13.0

8 files

1.12.0

8 files

1.11.0

8 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page