Overseer

A command-line tool for scanning and managing code comments in your projects. It helps you track TODOs, FIXMEs, and other comment markers across your codebase.

Features

• 🔍 Scan for comment markers (TODO, FIXME, etc.) in your codebase
• 📁 Filter files by name (partial or exact match)
• 🎯 Customizable comment markers to include/exclude
• 📝 Show code context around comments
• 📤 Export results to different formats (text, JSON, PDF)
• 🚫 Respects .gitignore patterns
• 🔒 Skip hidden files and directories

Configuration and compatibility

Supported languages

• TypeScript
• JavaScript
• Python
• C/C++
• Java
• Ruby
• PHP

To add support for a new language, you would simply add its patterns to the COMMENT_PATTERNS dictionary in config.py.

Default markers

• TODO
• FIXME
• REVIEW
• NOTE
• !
• ?

You can add your own markers by editing the config.py file.

Installation

Clone the repository

git clone https://github.com/tcsenpai/overseer.git
cd overseer

Install dependencies

pip install -r requirements.txt

or, using uv:

NOTE: Using uv, you can run the script directly without installing dependencies as uv run python main.py (see below for usage), as the pyproject.toml file is present. You can still install dependencies using the command below if you prefer.

uv pip install -r requirements.txt

Usage

python main.py --help

or, using uv:

uv run python main.py --help

usage: main.py [-h] [--workspace WORKSPACE] [--skip SKIP [SKIP ...]] [--include-all] [--no-context] [--export {pdf,xlsx}] [--output OUTPUT]
               [--filename FILENAME] [--complete-match] [--case-sensitive]

Scan TypeScript project comments

options:
  -h, --help            show this help message and exit
  --workspace WORKSPACE, -w WORKSPACE
                        Path to the workspace directory
  --skip SKIP [SKIP ...], -s SKIP [SKIP ...]
                        Markers to skip (e.g., --skip NOTE TODO)
  --include-all, -a     Include all markers (override default skip)
  --no-context, -nc     Don't show context lines around comments
  --export {pdf,xlsx}, -e {pdf,xlsx}
                        Export format (pdf or xlsx)
  --output OUTPUT, -o OUTPUT
                        Output file path for export

filename filtering:
  --filename FILENAME, -f FILENAME
                        Filter files by filename (case insensitive by default)
  --complete-match, -c  Match complete filename instead of partial (only with -f)
  --case-sensitive, -C  Make filename filter case sensitive (only with -f)

Examples

  main.py                                    # Scan all files with default settings
  main.py -w /path/to/project               # Scan a specific workspace
  main.py -f test.py                        # Find comments in files containing 'test.py' (case insensitive)
  main.py -f test.py -c                     # Find comments in files named exactly 'test.py'
  main.py -f Test.py -C                     # Find comments with case-sensitive filename match
  main.py -f test.py -c -C                  # Find comments in files named exactly 'test.py' (case sensitive)
  main.py --skip TODO FIXME                 # Skip TODO and FIXME comments
  main.py -a                                # Include all comment types
  main.py -e pdf -o comments.pdf            # Export comments to PDF

Command Line Options

Option	Short	Description
--workspace	-w	Specify workspace directory to scan
--filename	-f	Filter files by name (case insensitive by default)
--complete-match	-c	Match complete filename instead of partial
--case-sensitive	-C	Make filename filter case sensitive
--skip		Skip specified comment markers
--include-all	-a	Include all comment types
--no-context		Hide code context around comments
--export	-e	Export format (text, json, pdf)
--output	-o	Output file path

Configuration

The tool respects:

• .gitignore patterns in your project
• Hidden files and directories (starting with .)
• Project-specific file patterns (configured in config.py)