tingle¶

Code metrics for the era of constant refactoring.

tingle measures things you want to shrink (or watch) while refactoring a codebase: ignored lint rules, inline # noqa / # type: ignore comments, uses of a legacy class during a strangler-fig migration, lines of code in a package that should disappear.

It runs once, prints the numbers, and stores nothing. To watch a number over months, the metrics-history action records a point per commit that lands and publishes a chart of them.

Spider-sense for refactoring: you know that tingle — the itch that says the codebase isn't right yet. This tool puts a number on it, so you can watch it drop.

Install¶

pip install tingle

Setup¶

Copy this prompt to set up tingle in your project:

Set up tingle (https://tingle.fancysnake.dev) in this repository.

1. In Claude Code, install the tingle-config skill:
   `claude plugin marketplace add fancysnake/tingle`, then
   `claude plugin install tingle-config@tingle`. Other agents skip to the
   URL in step 2.
2. Set up tingle by following that skill. If it has not loaded in this
   session, read it from
   https://github.com/fancysnake/tingle/blob/main/plugins/tingle-config/skills/tingle-config/SKILL.md
   instead.

Quick start¶

tingle init                                    # starter tingle.toml
tingle library                                 # ready-made metrics for known tools
tingle add --base tingle.builtins.ruff.noqa_comment
tingle add regex_count '#\s*noqa'              # or state one yourself
tingle add toml_list_length tool.ruff.lint.ignore --name ruff-ignores
tingle                                         # interactive mode (on a terminal)
tingle stat                                    # summary table
tingle stat --json                             # machine-readable output
tingle stat --diff                             # impact of the current branch
tingle report                                  # every occurrence, file:line
tingle report --diff                           # what the branch added/removed
tingle report --group linting                  # one group, or --metric NAME

What it does¶

Three things, in rising order of opinion:

Measure. tingle stat counts what you told it to count and prints the numbers. Metric values never affect the exit code — tingle measures, it does not judge.
Attribute. tingle stat --diff measures only what the current branch changed, against the merge-base with a base branch, so commits that landed on the base after you branched don't pollute your numbers.
Judge. tingle check is the CI gate: the same branch measurement, but it exits 1 if the branch made things worse, so a pull request that takes on debt fails the build.

$ tingle check
noqa-comment (regex_count): +2
  + src/api/views.py:23
  + src/api/views.py:41

$ echo $?
1

Badge¶

Show that a repository keeps its debt in check with tingle:

[![tech debt: watched by tingle](https://img.shields.io/badge/tech%20debt-watched%20by%20tingle-c62828)](https://tingle.fancysnake.dev)

Where to go next¶

Configuration — tingle.toml, ranges, groups.
Metric types — what you can count, and the limits of each counter.
Template library — ready-made metrics for the tools you already run, and publishing your own.
Branch impact — how --diff attributes changes to your branch.
CI gate — failing the build on new debt.
History — recording the numbers per commit and publishing a chart of them. tingle's own is the shape of the result.
CLI reference — every command and flag.
Changelog — what each release changed.
Mission — why tingle exists, what it stands for, and what it deliberately is not.
Contributing — setup, the checks, and the layout of the source.