{"id":48533868,"url":"https://github.com/mikeckennedy/tallyman","last_synced_at":"2026-04-08T01:01:51.047Z","repository":{"id":337385842,"uuid":"1146213099","full_name":"mikeckennedy/tallyman","owner":"mikeckennedy","description":"A command-line tool that summarizes the size of a codebase by language, showing lines of code with and without comments and blank lines.","archived":false,"fork":false,"pushed_at":"2026-02-28T21:32:19.000Z","size":988,"stargazers_count":41,"open_issues_count":3,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-01T00:44:16.934Z","etag":null,"topics":["line-counter","metrics","metrics-gathering","metrics-visualization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikeckennedy.png","metadata":{"files":{"readme":"README.md","changelog":"change-log.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-30T19:16:57.000Z","updated_at":"2026-02-28T21:32:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mikeckennedy/tallyman","commit_stats":null,"previous_names":["mikeckennedy/tallyman"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mikeckennedy/tallyman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeckennedy%2Ftallyman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeckennedy%2Ftallyman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeckennedy%2Ftallyman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeckennedy%2Ftallyman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikeckennedy","download_url":"https://codeload.github.com/mikeckennedy/tallyman/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeckennedy%2Ftallyman/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31535203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["line-counter","metrics","metrics-gathering","metrics-visualization"],"created_at":"2026-04-08T01:01:50.982Z","updated_at":"2026-04-08T01:01:51.041Z","avatar_url":"https://github.com/mikeckennedy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tallyman\n\n**Know the shape of your project, not just the size.**\n\nTallyman 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.\n\n[![PyPI](https://img.shields.io/pypi/v/tallyman-metrics?v=2)](https://pypi.org/project/tallyman-metrics/)\n[![Python](https://img.shields.io/pypi/pyversions/tallyman-metrics?v=2)](https://pypi.org/project/tallyman-metrics/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n![Tallyman output showing language breakdown with colored percentage bar for a Python web project](https://mkennedy-shared.nyc3.digitaloceanspaces.com/github/tallyman-for-commandbook.webp)\n\n## Install\n\n```bash\nuv tool install tallyman-metrics\n```\n\nThen just point it at a project:\n\n```bash\ntallyman                    # analyze current directory\ntallyman /path/to/project   # analyze a specific path\ntallyman --setup            # re-run the interactive setup\ntallyman --no-color         # disable colored output\ntallyman --image            # save a PNG summary card to Desktop\ntallyman --image-light      # light-themed PNG variant\ntallyman --with-spaces      # use total lines (incl. comments/blanks) for totals\n```\n\n## Why Tallyman?\n\nTools like [cloc](https://github.com/AlDanial/cloc), [tokei](https://github.com/XACode/tokei), and [scc](https://github.com/boyter/scc) are excellent at counting lines of code. If all you need is raw numbers, they're great choices.\n\nBut 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?\n\n**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.\n\nA few things that set it apart:\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **Visual composition bar** - A colored percentage bar at the bottom shows you the language distribution of your project in a single glance.\n\n\n## Features\n\n- **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\n- **Six categories** - Code, DevOps, Design, Docs, Specs, and Data, each with aggregated totals\n- **40 languages** - From Python and Rust to Terraform and Docker, with full template support for HTML (Jinja, Nunjucks, Handlebars, and more)\n- **Beautiful output** - Colored, formatted results with a language composition bar, powered by [Rich](https://github.com/Textualize/rich)\n- **Realistic metrics** - Only counts files *you* wrote, not third-party dependencies or generated code\n- **Persistent config** - Your setup choices are saved to `.tally-config.toml` and reused on every run\n- **Image export** - Generate a shareable PNG summary card with `--image` (dark) or `--image-light` (light theme)\n- **Interactive TUI setup** - Visual directory tree for configuring exclusions and spec directories, powered by [Textual](https://github.com/Textualize/textual)\n\n![Tallyman interactive TUI setup showing directory tree with include/exclude toggles and spec directory markers](https://mkennedy-shared.nyc3.digitaloceanspaces.com/github/tallyman-setup.webp)\n\n## Image Export\n\nWant 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:\n\n```bash\ntallyman --image              # dark theme (default)\ntallyman --image-light        # light theme\n```\n\nThe 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](https://commandbookapp.com):\n\n![Tallyman image export showing code stats for the CommandBook app - category breakdown with colored language composition bar](https://mkennedy-shared.nyc3.digitaloceanspaces.com/github/commandbookapp-code-stats-example.png)\n\nThe 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.\n\n## Supported Languages\n\nTallyman recognizes **40 languages** across six categories:\n\n| Category | Languages |\n|----------|-----------|\n| **Code** | Python, Rust, Go, JavaScript, TypeScript, Java, C, C++, C#, Swift, Kotlin, Ruby, Shell, Lua, PHP, Perl, R, Dart, Scala, Elixir, Zig, Haskell, Erlang, OCaml, Nim, V |\n| **DevOps** | Terraform, Makefile, Docker |\n| **Design** | CSS, SCSS, LESS, HTML (+ 12 template formats), SVG |\n| **Docs** | Markdown, reStructuredText |\n| **Specs** | Markdown and reStructuredText files auto-detected in spec directories |\n| **Data** | TOML, YAML, JSON, XML, SQL |\n\n\u003cdetails\u003e\n\u003csummary\u003eFull language details with file extensions\u003c/summary\u003e\n\n### Code\n\n| Language | Extensions / Filenames |\n|----------|----------------------|\n| Python | `.py` |\n| Rust | `.rs` |\n| Go | `.go` |\n| JavaScript | `.js`, `.jsx`, `.mjs` |\n| TypeScript | `.ts`, `.tsx` |\n| Java | `.java` |\n| C | `.c` |\n| C Header | `.h` |\n| C++ | `.cpp`, `.hpp`, `.cc`, `.cxx` |\n| C# | `.cs` |\n| Swift | `.swift` |\n| Kotlin | `.kt`, `.kts` |\n| Ruby | `.rb` |\n| Shell | `.sh`, `.bash`, `.zsh` |\n| Lua | `.lua` |\n| PHP | `.php` |\n| Perl | `.pl`, `.pm` |\n| R | `.r`, `.R` |\n| Dart | `.dart` |\n| Scala | `.scala` |\n| Elixir | `.ex`, `.exs` |\n| Zig | `.zig` |\n| Haskell | `.hs` |\n| Erlang | `.erl` |\n| OCaml | `.ml`, `.mli` |\n| Nim | `.nim`, `.nims` |\n| V | `.v`, `.vv` |\n\n### DevOps\n\n| Language | Extensions / Filenames |\n|----------|----------------------|\n| Terraform | `.tf`, `.tfvars` |\n| Makefile | `.mk`, `Makefile`, `makefile`, `GNUmakefile` |\n| Docker | `.dockerfile`, `Dockerfile*`, `docker-compose.yml/yaml`, `compose.yml/yaml` |\n\n### Design\n\n| Language | Extensions |\n|----------|-----------|\n| CSS | `.css` |\n| SCSS | `.scss` |\n| LESS | `.less` |\n| HTML | `.html`, `.htm`, `.xhtml`, `.shtml`, `.pt`, `.jinja`, `.jinja2`, `.j2`, `.njk`, `.hbs`, `.ejs`, `.mustache` |\n| SVG | `.svg` |\n\n### Docs\n\n| Language | Extensions |\n|----------|-----------|\n| Markdown | `.md`, `.mdx` |\n| reStructuredText | `.rst` |\n\n### Data\n\n| Language | Extensions |\n|----------|-----------|\n| TOML | `.toml` |\n| YAML | `.yml`, `.yaml` |\n| JSON | `.json` |\n| XML | `.xml` |\n| SQL | `.sql` |\n\n\u003c/details\u003e\n\n## How It Works\n\nTallyman runs a simple pipeline:\n\n1. **Walk** your project directory, respecting gitignore patterns and your config exclusions\n2. **Identify** each file's language by extension (O(1) lookup)\n3. **Count** lines, classifying each as code, comment, or blank\n4. **Aggregate** results by language and category\n5. **Display** a colored report with per-language stats, category totals, and a composition bar\n\nSpec 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.\n\nComment detection covers single-line comment styles (`#`, `//`, `--`, `%`, `;`). Multi-line comment blocks (`/* */`, `\"\"\" \"\"\"`) are not currently detected - lines inside them are counted as code.\n\n## Configuration\n\nOn 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.\n\nTo re-run setup at any time:\n\n```bash\ntallyman --setup\n```\n\nTallyman also respects the `NO_COLOR` environment variable to disable colored output, following the [no-color.org](https://no-color.org) convention.\n\n## Requirements\n\n- Python 3.14+\n\n## Contributing\n\nContributions are welcome! Whether it's adding support for a new language, improving detection, or fixing a bug, we'd love the help.\n\n**Before opening a PR, please [create an issue](../../issues/new) 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.\n\n## License\n\nMIT License - Created by [Michael Kennedy](https://mkennedy.codes)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeckennedy%2Ftallyman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikeckennedy%2Ftallyman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeckennedy%2Ftallyman/lists"}