Introduction

towl is a fast command-line tool built in Rust that scans codebases for TODO comments. It provides an interactive TUI for browsing and managing TODOs, can create GitHub issues from them, and supports multiple output formats for CI/scripting. It detects TODO, FIXME, HACK, NOTE, and BUG comments across many languages, with configurable patterns, context-aware output, and robust resource limits.

Key Features

• Interactive TUI -- Browse, filter, sort, and peek at TODOs in a full-screen terminal interface powered by ratatui
• GitHub integration -- Create GitHub issues from selected TODOs and automatically replace comments with issue links
• Multi-language support -- Scans Rust, Python, JavaScript, Go, Shell, and more via configurable comment prefixes and function patterns
• Multiple output formats -- JSON, CSV, Markdown, TOML, and terminal table (non-interactive mode)
• Type filtering & sorting -- Filter results by TODO type; sort by file, line, type, or priority
• Context-aware -- Captures surrounding code lines and enclosing function names
• Configurable -- Customise file extensions, exclude patterns, comment prefixes, and TODO patterns via .towl.toml
• Safe by design -- Path traversal protection, resource limits, symlink resolution, and secret handling for GitHub tokens
• Fast -- Concurrent file scanning, async I/O with tokio, compiled regex patterns, and static enum dispatch

How It Works

                ┌──────────┐
                │  Config   │  .towl.toml + env vars + git remote
                └────┬─────┘
                     │
                ┌────▼─────┐
                │  Scanner  │  Walks directory tree, scans files concurrently
                └────┬─────┘
                     │
                ┌────▼─────┐
                │  Parser   │  Matches comment prefixes + TODO patterns
                └────┬─────┘
                     │
              ┌──────┴──────┐
              │             │
        ┌─────▼────┐  ┌────▼─────┐
        │   TUI     │  │  Output   │  Non-interactive: formats + writes
        │ (default) │  │  (-N)     │
        └─────┬────┘  └──────────┘
              │
        ┌─────▼────┐
        │ Processor │  Replaces TODOs with GitHub issue links
        └──────────┘

1. Config loads settings from .towl.toml (with defaults), merges environment variables for GitHub integration
2. Scanner walks the directory tree using the ignore crate, scanning matching files concurrently with bounded parallelism
3. Parser reads each file, matches comment prefixes and TODO patterns via compiled regex, extracts context lines and function names
4. TUI (default) presents an interactive interface for browsing, filtering, and selecting TODOs to create as GitHub issues
5. Output (non-interactive) formats the collected TodoComment items into the requested format and writes to a file or stdout
6. Processor replaces TODO comments in source files with GitHub issue links after issues are created

Quick Example

# Scan current directory (opens interactive TUI)
towl scan

# Non-interactive: output as terminal table
towl scan -N

# Non-interactive: output to JSON file
towl scan -N -f json -o todos.json

# Filter to only FIXME comments
towl scan -N -t fixme

# Create GitHub issues
towl scan -N -g

# Show current configuration
towl config