Tallyman
Know the shape of your project, not just the size.
Tallyman is a command-line tool that gives you a real picture of your codebase - not just raw line counts, but where your effort actually lives. It groups results into meaningful categories like Code, Design, Docs, Specs, and Data, so you can see at a glance whether your project is mostly Python logic, CSS styling, or Markdown documentation.
Install
uv tool install tallyman-metrics
Then just point it at a project:
tallyman # analyze current directory
tallyman /path/to/project # analyze a specific path
tallyman --setup # re-run the interactive setup
tallyman --no-save # use setup's choices for this run only, without writing a config
tallyman --no-color # disable colored output
tallyman --image # save a PNG summary card to Desktop
tallyman --image-light # light-themed PNG variant
tallyman --with-spaces # use total lines (incl. comments/blanks) for totals
tallyman --exclude 'tests/' # leave out files matching a pattern, for this run only
tallyman --exclude-rust-tests # leave out Rust #[cfg(test)] code, for this run only (--no-... counts it)
Why Tallyman?
Tools like cloc, tokei, and scc are excellent at counting lines of code. If all you need is raw numbers, they're great choices.
But line counts alone don't tell you much about a project's shape. Is your codebase mostly application logic, or has the CSS layer quietly grown to rival your backend? Are those Markdown files general docs, or are they specifications driving your development? How much of your project is configuration and data files versus actual code?
Tallyman answers these questions. It organizes every recognized file into one of six categories - Code, DevOps, Design, Docs, Specs, and Data - and shows you both the raw line count and the "effective" line count (excluding comments and blank lines) for each.
A few things that set it apart:
- Category-aware analysis - Results grouped by intent, not just by file extension. You see what kind of work your project contains, not just how many lines of each language.
- Automatic spec detection - Markdown and reStructuredText files in directories like
specs/,plans/, oragents/are automatically reclassified from Docs to Specs. If you're using planning documents to drive development (especially with AI-assisted workflows), Tallyman tracks that separately. - Interactive first-run setup - The first time you run Tallyman in a project, before any
.tally-config.tomlapplies, it launches a TUI where you can walk your project's directory tree and mark directories to exclude or flag as spec directories. Your choices are saved to.tally-config.tomlso subsequent runs are instant. - Gitignore-aware - Tallyman follows the same rules as Git: every
.gitignorein your tree, plus the repository'sinfo/exclude(in worktrees and submodules too), scoped and prioritised the way Git does it. Git repositories inside your project are counted with their own rules (see Git repositories inside your project). It skips virtual environments,node_modules, build artifacts, and anything else you've already told Git to ignore. - Visual composition bar - A colored percentage bar at the bottom shows you the language distribution of your project in a single glance.
Features
- Dual line counts - Total lines and effective lines (excluding comments and blanks) per language. Use
--with-spacesto base summaries and percentages on total lines instead - Six categories - Code, DevOps, Design, Docs, Specs, and Data, each with aggregated totals
- 44 languages - From Python and Rust to Solidity, Terraform, and Docker, with full template support for HTML (Jinja, Nunjucks, Handlebars, and more)
- Beautiful output - Colored, formatted results with a language composition bar, powered by Rich
- Realistic metrics - Only counts files you wrote, not third-party dependencies or generated code
- Persistent config - Your setup choices are saved to
.tally-config.tomland reused on every run, or used once and never written with--no-save - File patterns - Gitignore-style
[exclude] patternsfor files a directory exclude can't reach, such as Rust tests beside the code they test, and--exclude PATTERNto leave files out of one run without touching the config - Rust test code - Opt in with
[rust] exclude_test_modulesto leave inline#[cfg(test)]modules and helpers out of the count, or--exclude-rust-testsfor one run - Image export - Generate a shareable PNG summary card with
--image(dark) or--image-light(light theme) - Interactive TUI setup - Visual directory tree for configuring exclusions and spec directories, powered by Textual
Image Export
Want to share your project's code stats in a README, a slide deck, or a social post? Use --image to generate a clean PNG summary card:
tallyman --image # dark theme (default)
tallyman --image-light # light theme
The image is saved to your Desktop (or the current directory if no Desktop is found) with a filename based on the project name. Here's an example from the CommandBook macOS app:
The card includes category totals with effective line counts, a colored language composition bar, and a legend that marks each language with a swatch of its bar color - everything you need to show the shape of your project at a glance. The bar and legend name up to five of the largest languages (each at least 2% of the total) and group the rest as Other, and a legend too long for one row wraps onto more rows.
Supported Languages
Tallyman recognizes 44 languages across six categories:
| Category | Languages |
|---|---|
| Code | Python, Rust, Go, JavaScript, TypeScript, Java, C, C/C++ Header, C++, C#, Swift, Kotlin, Ruby, Shell, Lua, PHP, Perl, R, Dart, Scala, Elixir, Zig, Haskell, Erlang, OCaml, Nim, V, Solidity, MATLAB |
| DevOps | Terraform, Makefile, Docker |
| Design | CSS, SCSS, LESS, HTML (+ 8 template extensions), SVG |
| Docs | Markdown, reStructuredText |
| Specs | Markdown and reStructuredText files auto-detected in spec directories |
| Data | TOML, YAML, JSON, XML, SQL |
Full language details with file extensions
Extensions match in any case, so analysis.R is R and README.MD is Markdown.
Code
| Language | Extensions / Filenames |
|---|---|
| Python | .py |
| Rust | .rs |
| Go | .go |
| JavaScript | .js, .jsx, .mjs |
| TypeScript | .ts, .tsx |
| Java | .java |
| C | .c |
| C/C++ Header | .h |
| C++ | .cpp, .hpp, .cc, .cxx |
| C# | .cs |
| Swift | .swift |
| Kotlin | .kt, .kts |
| Ruby | .rb |
| Shell | .sh, .bash, .zsh |
| Lua | .lua |
| PHP | .php |
| Perl | .pl, .pm |
| R | .r |
| Dart | .dart |
| Scala | .scala |
| Elixir | .ex, .exs |
| Zig | .zig |
| Haskell | .hs |
| Erlang | .erl |
| OCaml | .ml, .mli |
| Nim | .nim, .nims |
| V | .v, .vv |
| Solidity | .sol |
| MATLAB | .m |
DevOps
| Language | Extensions / Filenames |
|---|---|
| Terraform | .tf, .tfvars |
| Makefile | .mk, Makefile, makefile, GNUmakefile |
| Docker | .dockerfile, Dockerfile, Dockerfile.* / Dockerfile-* / Dockerfile_* (except a docs or data extension such as Dockerfile.md or Dockerfile.json, and .txt or .dockerignore), docker-compose.yml/yaml, compose.yml/yaml and variants such as docker-compose.override.yml |
Design
| Language | Extensions |
|---|---|
| CSS | .css |
| SCSS | .scss |
| LESS | .less |
| HTML | .html, .htm, .xhtml, .shtml, .pt, .jinja, .jinja2, .j2, .njk, .hbs, .ejs, .mustache |
| SVG | .svg |
Docs
| Language | Extensions |
|---|---|
| Markdown | .md, .mdx |
| reStructuredText | .rst |
Data
| Language | Extensions |
|---|---|
| TOML | .toml |
| YAML | .yml, .yaml |
| JSON | .json |
| XML | .xml |
| SQL | .sql |
How It Works
Tallyman runs a simple pipeline:
- Walk your project directory, respecting
.gitignoreand your config's exclusions and patterns - Identify each file's language by extension or filename
- Count lines, classifying each as code, comment, or blank (with
[rust] exclude_test_modules, Rust test-only code is left out first) - Aggregate results by language and category
- Display a colored report with per-language stats, category totals, and a composition bar
Spec directories (specs/, plans/, specifications/, agents/) are auto-detected at any depth. Any Markdown or reStructuredText files inside them are reclassified from Docs to Specs, giving you a clear picture of how much of your project is specification-driven.
Lines end at \n, \r\n or a lone \r, and a last line without a newline still counts. Files with a UTF-8, UTF-16 or UTF-32 byte-order mark are decoded accordingly; anything else is read as UTF-8.
Some files are never counted, whatever your .gitignore says:
- Hidden directories such as
.git/,.venv/and.github/ - Binary files (a NUL byte in the first 8 KB)
- Symlinks, so a linked file is never counted twice, and special files such as named pipes and sockets
- Generated files:
.tally-config.toml,package-lock.json,npm-shrinkwrap.json,pnpm-lock.yaml,*.min.jsand*.min.css
Comment detection covers single-line comment styles (#, //, --, %). Multi-line comment blocks (/* */, """ """) are not currently detected - lines inside them are counted as code.
Git repositories inside your project
Tallyman counts Git repositories nested inside your project, including submodules and worktrees, with their own rules, as if you ran Git inside each one. A nested repository's own .gitignore files and info/exclude apply, and your outer repository's .gitignore stops at the nested repository's folder. If the outer repository ignores that folder itself, the nested repository stays out (tallyman path/to/it still counts it). A folder of checkouts that isn't a repository works the same way: its .gitignore stops at each repository inside it.
Your .tally-config.toml settings are different. [exclude], [specs] and [rust] settings, and configs in subdirectories, apply inside nested repositories too, since they're your instructions for the scan, not Git's. Scanning inside a nested repository uses only its own configs (see "Which configs apply" under Configuration).
Where Tallyman and Git differ:
- Matching is always case-sensitive, even where Git ignores case (the macOS default).
- Your global Git excludes file (
core.excludesFile, usually~/.config/git/ignore) isn't read, so counts are the same on every machine. - A tracked file under an ignored pattern is skipped. Git keeps files it already tracks, but Tallyman doesn't read Git's index.
- Any
.gitfolder or file starts a nested repository, even an empty or broken one that Git would treat as an ordinary folder. - A
.gitignorethat is a symlink is read. Git (2.32 and later) skips it with a warning.
Configuration
When no .tally-config.toml applies yet, Tallyman starts with an interactive TUI where you can browse your project tree and configure which directories to exclude or mark as spec directories. Your choices are saved to .tally-config.toml in the directory you scanned. A config in the scanned directory or any directory above it (see Which configs apply below) means setup is skipped; one in a subdirectory doesn't. So once the repository root has a config, tallyman src/ counts straight away, using it; run tallyman --setup src/ to give src/ its own config.
To re-run setup at any time:
tallyman --setup
In the TUI, x excludes or includes a directory, and s marks or unmarks it as specs. Pressing s on a directory Tallyman detected as specs (such as plans/) records that it isn't one. In a project with Rust code, r switches Rust test code between counted and left out (see Leaving out Rust test code).
The config is plain TOML, and you can edit it by hand:
[exclude]
directories = ["static/vendor", "docs/_build"]
[specs]
directories = ["design"] # also count these as specs
ignore = ["src/myapp/agents"] # never specs, even if named plans/, agents/, ...
- Paths are relative to the directory the config file lives in. An entry covers everything beneath it.
- A config saved with a byte-order mark (some Windows editors add one) is read fine.
- In
[specs],"."means that directory itself. - When
directoriesandignoredisagree, the deeper entry wins, so you can ignoreagents/but still countagents/plans/. If both list the same directory,directorieswins.
Which configs apply. Every .tally-config.toml from the root of the Git repository down to the directory you scan applies, not just the nearest one. That is the nearest repository, so scanning inside a nested repository doesn't pick up the outer project's configs. Outside a repository, Tallyman only looks in the scanned directory itself.
- Each config is applied relative to where it lives, so
tallyman src/honours the project's exclusions as well as any config insrc/. - Exclusions from every config add up. For specs, the deeper entry wins, and when two configs name the same directory, the deeper config wins.
- A parent's exclusion of the directory you scan, or of one above it, is skipped: you asked to scan it.
tallyman --setupedits only the config in the scanned directory. Settings from parent configs are shown as "(set in a parent config)", and those from configs in subdirectories as "(set in a nested config)". Neither can be changed there; they stay in their own file, so editing it later reaches every directory below it. Copies of either kind that earlier versions wrote into the scanned directory's config are removed the next time setup saves. A directory a parent or nested config excludes is shown without its contents.- If your home directory is itself a Git repository, as some dotfiles setups are, a
~/.tally-config.tomlapplies to every directory below it that isn't in its own repository. - Configs in subdirectories are merged in as Tallyman walks into them. They can add exclusions but can't re-include a directory excluded above. Their spec settings follow the same deeper-wins rules, so a subdirectory's
ignore = ["."]turns specs off for that subtree. - A broken config at or above the directory you scan stops the run with a message naming the file. A broken config in a subdirectory is skipped without a message, so scanning from the repo root and scanning from inside that subdirectory can differ.
Without a config file. To keep .tally-config.toml out of a project you only measure now and then, pass --no-save. Setup opens as usual, its button reads Run instead of Save & Run, and your choices apply to that run only. Nothing is written, so the next run opens setup again. Configs that already apply are still read, and tallyman --setup --no-save tries other settings without changing the config. For one-off tweaks without setup, see --exclude and --exclude-rust-tests below.
Without a terminal, such as in CI or a pipe, a first run counts with default settings, writes no config, and prints a one-line note. --setup needs an interactive terminal.
Tallyman also respects the NO_COLOR environment variable to disable colored output, following the no-color.org convention.
Excluding files by pattern
Some files can't be reached by excluding a directory. Some Rust projects, for example, keep unit tests in files beside the code they test: src/routing/tests.rs next to src/routing/handlers.rs. Excluding src/routing would drop the real code too. For those, add gitignore-style patterns:
[exclude]
directories = ["target"]
patterns = [
"tests.rs",
"testing.rs",
"!src/keep/tests.rs",
]
- Patterns use
.gitignoresyntax and are matched relative to the directory of the config that declares them. - Patterns, like directory excludes, apply inside nested Git repositories too, when you scan from outside them.
- A pattern without a slash, like
tests.rs, matches at any depth, so**/tests.rsisn't needed. - A pattern with a slash at the start or in the middle, like
/tests.rsorsrc/routing/tests.rs, is matched from the config's directory. Use**/routing/tests.rsto match at any depth. - A trailing
/matches directories only, such asfixtures/. - Within one config, later lines win, so
!src/keep/tests.rsaftertests.rskeeps that one file. Order matters, and setup keeps it. - Patterns layer like nested
.gitignorefiles: a deeper config's!tests.rsbrings back what a shallower config'stests.rsexcluded. - A
!only undoes other patterns. It never brings back gitignored files, excluded or hidden directories, or the files Tallyman always skips. As in Git, it also can't bring back a file whose directory a pattern excluded:fixtures/plus!fixtures/keep.pykeeps nothing. - A parent config's patterns never exclude the directory you scan, so a parent's
app/doesn't emptytallyman app/. A parent'sapp/**does, since it matches the files inside rather than the directory, just as it would in Git. - Setup shows directories a pattern excludes as "(excluded by pattern)", unless a config's
directorieslist excludes them too: that is checked first, so they show as excluded by that config, and an entry in the scanned directory's config can still be toggled off. It doesn't edit patterns, but keeps them, in order, when it rewrites the config. Because setup can't re-create them, re-runningtallyman --setupto replace a broken config loses its patterns. Fix the file by hand if it has any. - When patterns remove anything, the report ends with a line such as
Excluded by [exclude] patterns: 12 files, 1 directory. It counts files Tallyman would otherwise have counted, plus the directories a pattern skipped. Files inside a skipped directory aren't looked at, so they aren't in the file count.
For one run: --exclude
To see how big a project is without some files, without editing the config, pass patterns on the command line:
tallyman --exclude 'tests/' --exclude 'tests.rs'
- Each
--excludeis one pattern in the same.gitignoresyntax, matched from the directory you scan, as if it were a line in that directory's config. The current directory plays no part:tallyman ../proj --exclude 'src/gen/'leaves out../proj/src/gen. Writesrc/gen/or/src/gen/, not./src/gen/or an absolute path. A value that starts with-needs the=form:--exclude=-draft.py. - They are the last word: they apply after every config's patterns, nested configs included, so a crate's
!tests/doesn't bring back what--exclude 'tests/'left out. Among themselves, later ones win. - A
!brings back what a config pattern excluded (--exclude '!src/keep/tests.rs'). Like any pattern, it never brings back gitignored files, excluded or hidden directories, or the files Tallyman always skips. - They are never saved. Setup, whether from
--setupor a first run, doesn't show them and doesn't write them; the count after it leaves them out. - What they remove is counted in the same
Excluded by [exclude] patternsline. - A pattern that can never match stops the run (exit code 2) before anything is counted: an empty one, a comment (
#gen; write\#genfor a name starting with#), a lone!or/, a value spanning lines, a path with an empty,.or..segment (./src/gen/,a//b,../x), or an absolute path into the scanned directory. The error suggests the fix where there is one:./src/gen/becomes/src/gen/.
Inline Rust test modules (#[cfg(test)] mod tests { ... }) share a file with the code they test, so no pattern can reach them. For those, see the next section.
Leaving out Rust test code
Rust keeps most unit tests in a module at the bottom of the file it tests. To count only the code that ships, turn this on:
[rust]
exclude_test_modules = true
With it on, the test module below drops out of the count, and the three lines of parse still count:
pub fn parse(input: &str) -> usize {
input.len()
}
#[cfg(test)] // from here to the closing brace: not counted
mod tests {
#[test]
fn parses() {
assert_eq!(super::parse("ab"), 2);
}
}
- What counts as test code. Any item marked
#[cfg(test)], not justmod tests: a test-onlyfn,use,structorimpl, and test-only methods inside animplortrait. Doc comments and other attributes on that item go with it, and code after it still counts. #[cfg(all(test, ...))]counts too, since it is test-only.#[cfg(any(test, ...))]doesn't: that code also builds outside tests.- A file or module that starts with
#![cfg(test)]is test code from top to bottom. - What it leaves alone.
#[cfg(test)]on a statement inside a function, on a struct field, an enum variant or a match arm, and insidemacro_rules!bodies.#[cfg(test)] mod tests;: only that declaration drops. The file it points at counts as usual, unless it starts with#![cfg(test)]. Otherwise exclude it with a pattern such aspatterns = ["tests.rs"], or for one run,--exclude 'tests.rs'.- Integration tests in
tests/, benches and examples: exclude those directories.
- Where it applies. It applies by directory, like every other setting. A config in a crate's directory can turn it on or off for that crate, and
falseoverrides a parent'strue. - Setup. When the project has Rust code,
--setupshows aRust test code: counted(orexcluded) line under the tree, andrswitches it. Pressingrsaves the setting only when it differs from what parent configs give, so pressing it twice leaves the config as it was; untouched, the config's value is kept as written. Rust in a directory whose own config sets[rust]follows that config: the line says so, andrchanges only the rest. Without Rust code the line and the key don't appear. - For one run.
--exclude-rust-testsleaves test code out and--no-exclude-rust-testscounts it, whatever the configs say, nested crate configs included. Neither is saved, and setup ignores them: its line shows, andrchanges, the config's value, while the count after setup uses the flag. Given both, the last one wins. - When something is left out, the report ends with a line such as
Excluded Rust test code: 2,412 lines in 37 files. It counts every line left out, blank and comment lines included, so the totals, which leave those out by default, drop by less. A file that was all test code isn't counted as a Rust file. - If Tallyman can't follow a file (an unterminated string, brackets that don't balance), it counts the whole file. It may miss some test code, but it never leaves out real code.
Requirements
- Python 3.14+
Contributing
Contributions are welcome! Whether it's adding support for a new language, improving detection, or fixing a bug, we'd love the help.
Before opening a PR, please create an issue first to discuss what you have in mind. This helps make sure your idea aligns with the direction of the project and saves everyone time. Once we've agreed on the approach, fire away with the pull request.
License
MIT License - Created by Michael Kennedy
Metadata
Release files for tallyman-metrics 0.4.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tallyman_metrics-0.4.3.tar.gz | 1.1 MB | Without provenance | Details for tallyman_metrics-0.4.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tallyman_metrics-0.4.3-py3-none-any.whl | Python 3 | none | any | Details for tallyman_metrics-0.4.3-py3-none-any.whl |
Total release size: 1.4 MB
Release files / tallyman_metrics-0.4.3.tar.gz
| Download URL | tallyman_metrics-0.4.3.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
93c2cfc5755ee74b1c453159b76401233d3bb4601d0298012a719d8b63062ac7
|
|
BLAKE2b-256 checksum How to use checksums |
0c821c5688336db939e04e67ecf3843e37c26cf1701fce38dd6097ee4538234f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / tallyman_metrics-0.4.3-py3-none-any.whl
| Download URL | tallyman_metrics-0.4.3-py3-none-any.whl |
|---|---|
| Size | 324.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2a5367012be4e2155146b2303821dd1db08bb830bd7e64e64e69cd9b9eda5a9e
|
|
BLAKE2b-256 checksum How to use checksums |
3a8983ee2dc6c68c9c947f897bd962d61a662536b56fd24608d460e11b0b895b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for tallyman-metrics 0.4.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.