Codebase Inspection with pygount: LOC, Languages, and Ratios

This skill runs pygount on a local repository to produce a breakdown of lines of code by language, file counts, and code-to-comment ratios. You would reach for it when someone asks "how big is this repo?", "what languages are used?", or "what is the code-to-comment ratio?" and you want a quick, structured answer without leaving the terminal.

What it does

pygount scans a directory tree, identifies programming languages by file extension, and counts lines of code, comments, and empty lines. The skill wraps common invocations so you can get a summary table, filter by language, or export JSON for further processing. It is bundled with Hermes Agent and lives at skills/github/codebase-inspection.

Before you start

You need pygount installed. The skill tries to install it with --break-system-packages first (for newer pip on Linux), then falls back to a normal install. Run this once:

pip install --break-system-packages pygount 2>/dev/null || pip install pygount

The skill works on Linux, macOS, and Windows. You must already have the repository cloned locally and know its path.

1. Basic Summary (Most Common)

Get a full language breakdown with file counts, code lines, and comment lines:

cd /path/to/repo
pygount --format=summary \
  --folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,.eggs,*.egg-info" \
  .

IMPORTANT: Always use --folders-to-skip to exclude dependency/build directories, otherwise pygount will crawl them and take a very long time or hang.

2. Common Folder Exclusions

Adjust based on the project type:

# Python projects
--folders-to-skip=".git,venv,.venv,__pycache__,.cache,dist,build,.tox,.eggs,.mypy_cache"

# JavaScript/TypeScript projects
--folders-to-skip=".git,node_modules,dist,build,.next,.cache,.turbo,coverage"

# General catch-all
--folders-to-skip=".git,node_modules,venv,.venv,__pycache__,.cache,dist,build,.next,.tox,vendor,third_party"

3. Filter by Specific Language

# Only count Python files
pygount --suffix=py --format=summary .

# Only count Python and YAML
pygount --suffix=py,yaml,yml --format=summary .

4. Detailed File-by-File Output

# Default format shows per-file breakdown
pygount --folders-to-skip=".git,node_modules,venv" .

# Sort by code lines (pipe through sort)
pygount --folders-to-skip=".git,node_modules,venv" . | sort -t$'\t' -k1 -nr | head -20

5. Output Formats

# Summary table (default recommendation)
pygount --format=summary .

# JSON output for programmatic use
pygount --format=json .

# Pipe-friendly: Language, file count, code, docs, empty, string
pygount --format=summary . 2>/dev/null

6. Interpreting Results

The summary table columns:

• Language, detected programming language
• Files, number of files of that language
• Code, lines of actual code (executable/declarative)
• Comment, lines that are comments or documentation
• %, percentage of total

Special pseudo-languages:

• __empty__, empty files
• __binary__, binary files (images, compiled, etc.)
• __generated__, auto-generated files (detected heuristically)
• __duplicate__, files with identical content
• __unknown__, unrecognized file types

Pitfalls

1. Always exclude .git, node_modules, venv, without --folders-to-skip, pygount will crawl everything and may take minutes or hang on large dependency trees.
2. Markdown shows 0 code lines, pygount classifies all Markdown content as comments, not code. This is expected behavior.
3. JSON files show low code counts, pygount may count JSON lines conservatively. For accurate JSON line counts, use wc -l directly.
4. Large monorepos, for very large repos, consider using --suffix to target specific languages rather than scanning everything.

When not to use it

If you need a live count from a remote repository without cloning it first, this skill is not the right tool. It works only on a local checkout. For repository management tasks like cloning, listing branches, or checking status, pair this with the github-repo-management skill.

Limits and gotchas

• The --folders-to-skip flag is essential; forgetting it is the most common failure mode.
• Markdown and JSON counts are intentionally conservative by design of pygount.
• The skill does not handle authentication or private repository access; you must have the repo cloned and readable.

What pairs with this

The related skill github-repo-management handles cloning, branch listing, and other repository operations that typically precede an inspection.