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:

Language	Comment Styles
C, C++, Rust, Go, Java, JavaScript, TypeScript	//, /* */
Python, Ruby, Shell, YAML	#
HTML, XML	<!-- -->
SQL	--, /* */
Lisp, Clojure	;
Lua	--

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:

Priority	Tags	Color
Critical	BUG, FIXME, ERROR	Red
High	HACK, WARN, WARNING, FIX	Yellow
Medium	TODO, WIP, MAYBE	Cyan
Low	NOTE, XXX, INFO, DOCS, PERF, TEST, IDEA	Green

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.