tingle
Documentation is at https://tingle.fancysnake.dev.
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
Metrics are declared in tingle.toml (or a [tool.tingle] section in
pyproject.toml):
[ranges.python]
include = ["src/**/*.py", "tests/**/*.py"]
default = true
[[metrics]]
name = "noqa-comments"
type = "regex_count"
pattern = '#\s*noqa'
You can count regex matches, uses of a Python symbol, entries in a TOML or
INI list (this is how you count ignored lint rules), files, and lines.
See the metric types.
For the tools everyone already runs there are ready-made definitions, so a
metric can name one and override only what differs:
[[metrics]]
base = "tingle.builtins.ruff.noqa_comment"
extra_ignore_lines = ['# @generated']
They live in an ordinary Python package, so your team can publish its own.
See the template library.
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:
[](https://tingle.fancysnake.dev)
Documentation
- Configuration —
tingle.toml, ranges, groups.
- Metric types — what you can
count, and the limits of each counter.
- Template library — ready-made
metrics for known tools, and publishing your own.
- Branch impact — how
--diff
attributes changes to your branch.
- CI gate — failing the build on new
debt.
- History — recording a point per
commit and publishing a chart per group, like
tingle's own.
- Claude Code plugin — the
tingle-config skill, which writes a project's config for you.
- 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.
Development
Python 3.11–3.15 are supported (CI runs the full matrix). The project uses
mise + Poetry.
mise install
poetry install
mise run test:py # tests
mise run lint:py # ruff, mypy, pylint, import-linter
mise run site:dev # preview the docs site
See contributing for
the GLIMPSE source layout and the layer contracts.
License
MIT.
