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.15.1.tar.gz (222.8 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.15.1-py3-none-win_amd64.whl (4.9 MB view details)

Uploaded Python 3Windows x86-64

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

Uploaded Python 3musllinux: musl 1.2+ x86-64

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

Uploaded Python 3musllinux: musl 1.2+ ARM64

knots-1.15.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.2 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ x86-64

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

Uploaded Python 3manylinux: glibc 2.17+ ARM64

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

Uploaded Python 3macOS 11.0+ ARM64

knots-1.15.1-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.15.1.tar.gz.

File metadata

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

File hashes

Hashes for knots-1.15.1.tar.gz
Algorithm Hash digest
SHA256 6e27bf12adff28002d33cd1b8612841a5edca4c01d00d115fdaaf11df3bb613e
MD5 9e05980e47eb2ac48b74b1ba53847bb7
BLAKE2b-256 4572f8da9d2ea79e68f5bb90940f85f36d2af508ac62382f4828de9423dac9cd

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.15.1.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.15.1-py3-none-win_amd64.whl.

File metadata

  • Download URL: knots-1.15.1-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.15.1-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 480ffcfd894d5d2bae0aebc93fa7eb4a133535f0ec57b775e57e96cb8e84e3ec
MD5 01a6e7d8afeaa6b233a6139bc9731996
BLAKE2b-256 9d467320a83208bd0c192474dceeb4a1bb0932956b2d97e7db76a33e0ba8d7a7

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.15.1-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.15.1-py3-none-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for knots-1.15.1-py3-none-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 0851508c7afaad4cbeb6648ed95d7fc4ee63300b4ff35ec5a91cb82d1cefae23
MD5 1f29ca52739fc1254e97c2b4223050b1
BLAKE2b-256 aabdcaa141fd9cb309c764b82c7ed179f840703bcfc3fd5b462cf07bd34a1333

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.15.1-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.15.1-py3-none-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for knots-1.15.1-py3-none-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 a4bee7e0da212a5d2df8383f496fa8b84433428cc6db4c878f506cde9105bfe4
MD5 817e4a74f7bc141c29e5e0fd9da848f8
BLAKE2b-256 35209ecf0bf0b8493a11e219b9e520b62ca08d7b8e7a04e33d64f764a785139e

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.15.1-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.15.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for knots-1.15.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 eb4492760895ac7d1534ab4af9bb641ec2a77c3faa06b5a4ddd95c0be894898b
MD5 e024985146a08c30c24c2a45b9f21f72
BLAKE2b-256 5d2d7b5682d76ee9782d9516a059c106c38433fdde8976ca07f7250cecfeac02

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.15.1-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.15.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for knots-1.15.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 d1ebf2389263858d7c3c4f6dbc3b4beb044b622176112c0f9a0f494a7792666c
MD5 f9d379525fa2400c3fe022d68207e960
BLAKE2b-256 2c0c0c8a21f0bc4e074990a002f119d32f125719c8e15534e39ba3422cd70322

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.15.1-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.15.1-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for knots-1.15.1-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 38a095825c1b7180b15d3367b1aa5c64b36b636a8c7922fc8a540113608b3b80
MD5 612a735b01305da5c958e761e81611ea
BLAKE2b-256 a6e7810f609b8f2b601925c5d519fafd6a468afe58239a13ec5f7e2dbcf0eb19

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.15.1-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.15.1-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for knots-1.15.1-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 14f9723595aa8ddb5f0b5683d162874101281ddd00571fd1359224323fe2a195
MD5 bf16e82404ead254492cf0ce350e0c2a
BLAKE2b-256 b021d57faeec0151e5a9c8ca2573a551cfb119f72bc4c23facece36f00a2b910

See more details on using hashes here.

Provenance

The following attestation bundles were made for knots-1.15.1-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

This release

1.15.1 This release

8 files

1.15.0

8 files

1.14.0

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