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-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

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/, or agents/ 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 - On first run, Tallyman 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.toml so subsequent runs are instant.
• Gitignore-aware - Tallyman reads your .gitignore and .git/info/exclude patterns automatically. 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-spaces to base summaries and percentages on total lines instead
• Six categories - Code, DevOps, Design, Docs, Specs, and Data, each with aggregated totals
• 40 languages - From Python and Rust to 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.toml and reused on every 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 compact legend - everything you need to show the shape of your project at a glance.

Supported Languages

Tallyman recognizes 40 languages across six categories:

How It Works

Tallyman runs a simple pipeline:

1. Walk your project directory, respecting gitignore patterns and your config exclusions
2. Identify each file's language by extension (O(1) lookup)
3. Count lines, classifying each as code, comment, or blank
4. Aggregate results by language and category
5. Display a colored report with per-language stats, category totals, and a composition bar

Spec directories (specs/, plans/, specifications/, agents/) are auto-detected. 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.

Comment detection covers single-line comment styles (#, //, --, %, ;). Multi-line comment blocks (/* */, """ """) are not currently detected - lines inside them are counted as code.

Configuration

On first run, Tallyman launches 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 project root.

To re-run setup at any time:

tallyman --setup

Tallyman also respects the NO_COLOR environment variable to disable colored output, following the no-color.org convention.

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