Todo Tree

A command-line tool to find and display TODO-style comments in your codebase, similar to the VS Code "Todo Tree" extension.

Features

• 🔍 Recursive directory scanning - Respects .gitignore rules automatically
• 🏷️ Configurable tags - TODO, FIXME, BUG, NOTE, HACK, WARN, PERF, and more (and custom tags)
• 🌳 Tree view output - Beautiful hierarchical display grouped by file
• 📋 Multiple output formats - Tree, flat list, and JSON
• ⚙️ Configuration file support - .todorc in JSON or YAML format
• 🎨 Colored output - Priority-based coloring for different tag types
• 🔗 Clickable links - Terminal hyperlinks to file locations (where supported)
• 🧩 Editor extensions - Integrates with Zed
• 🤖 GitHub Action - Automatically scan PRs and post TODO summaries as comments

Installation

Using Homebrew (macOS/Linux)

brew tap alexandretrotel/todo-tree
brew install todo-tree

Using Cargo

cargo install todo-tree

NixOS (Flakes)

Try before you install

# runs the default todo-tree command
nix run github:alexandretrotel/todo-tree

# create a shell with the command available (with nix-output-monitor)
nom shell github:alexandretrotel/todo-tree
tt tags

# or, just normal nix
nix shell github:alexandretrotel/todo-tree
tt scan ~/projects/todo-tree --tags FIXME

Note: If you haven't enabled the experimental Nix command and flakes features, you need to pass --extra-experimental-features "nix-command flakes" to the command. See the Nix command wiki for more details.

Install for your system

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    todo-tree.url = "github:alexandretrotel/todo-tree";
  };

  outputs = { self, nixpkgs, todo-tree, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [ ./configuration.nix ];
      specialArgs = { inherit todo-tree; };
    };
  };
}

# configuration.nix
{ pkgs, todo-tree, ... }:

{
  environment.systemPackages = [
    todo-tree.packages.${pkgs.stdenv.hostPlatform.system}.todo-tree
  ];
}

From Source

# Clone the repository
git clone https://github.com/alexandretrotel/todo-tree.git
cd todo-tree

# Build and install
cargo install --path .

Usage

The tool provides two binary names: todo-tree and tt (alias for quick access).

Basic Commands

# Scan current directory (default command)
tt

# Scan a specific directory
tt scan ./src

# Scan with specific tags
tt scan --tags TODO,FIXME,BUG

# List all TODOs in flat format
tt list

# Show configured tags
tt tags

# Show statistics
tt stats

Configuration

Create a .todorc.json or .todorc.yaml file in your project root:

JSON Format (.todorc.json)

{
  "tags": ["TODO", "FIXME", "BUG", "NOTE", "HACK", "XXX", "WARN", "PERF"],
  "include": ["*.rs", "*.py", "*.js", "*.ts"],
  "exclude": ["target/**", "node_modules/**", "dist/**"],
  "json": false,
  "flat": false,
  "no_color": false,
  "ignore_case": false,
  "require_colon": true
}

YAML Format (.todorc.yaml)

tags:
  - TODO
  - FIXME
  - BUG
  - NOTE
  - HACK

include:
  - "*.rs"
  - "*.py"

exclude:
  - "target/**"
  - "node_modules/**"

json: false
flat: false
no_color: false

Configuration Search Order

1. .todorc in the current directory
2. .todorc.json in the current directory
3. .todorc.yaml or .todorc.yml in the current directory
4. Parent directories (recursive)
5. ~/.config/todo-tree/config.json (global config)

Supported Comment Styles

The tool recognizes TODO-style tags in various comment formats:

Tag Formats Recognized

By default, todo-tree requires tags to be UPPERCASE and followed by a colon:

// TODO: This will be found ✓
// FIXME: This will be found ✓
// BUG: This will be found ✓

// todo: This will NOT be found (lowercase) ✗
// TODO This will NOT be found (no colon) ✗
// Todo: This will NOT be found (mixed case) ✗

Optional author/assignee syntax (still works with colon):

// TODO(john): Assigned to john ✓
// FIXME(team): Needs team review ✓

Flexible Matching Options

You can customize the matching behavior with CLI flags:

# Ignore case when matching (matches TODO, todo, Todo, etc.)
tt scan --ignore-case

# Allow tags without colon (matches "TODO something")
tt scan --no-require-colon

# Use both options together (most flexible, like v0.2.x behavior)
tt scan --ignore-case --no-require-colon

Or set these options in your .todorc.json:

{
  "ignore_case": true,
  "require_colon": false
}

Why These Defaults?

The strict defaults (uppercase + colon required) significantly reduce false positives:

• Code like std::io::Error in Rust/C++ won't match
• Variable names like ERROR_CODE won't match
• Prose like "this is an error" won't match
• Type definitions like Result<T, Error> won't match

These defaults align with most coding conventions and help you find intentional TODO comments, not accidental matches.

Priority Levels

Tags are assigned priority levels for sorting and coloring:

Terminal Support

Clickable Links

The tool generates clickable hyperlinks (OSC 8) in supported terminals:

• iTerm2
• WezTerm
• Hyper
• VS Code Terminal
• GNOME Terminal (VTE 0.50+)
• Konsole
• Alacritty

Color Support

Colors are automatically enabled when outputting to a terminal. Use --no-color or set the NO_COLOR environment variable to disable.

Related Projects

todo-tree-action

A GitHub Action that automatically scans your pull requests for TODO comments and posts a summary as a PR comment. Features include:

• Scan only changed files in PRs
• Filter to show only NEW TODOs (not in base branch)
• Automatic PR comment with formatted results
• Full configuration support

zed-todo-tree

A Zed Editor extension that integrates TODO scanning directly into Zed. Features include:

• Interactive results in the assistant panel
• Full configuration support
• Seamless editor integration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

Acknowledgments

• Inspired by the Todo Tree VS Code extension
• Built with clap, ignore, and regex

License

MIT License - see LICENSE for details.