Todo Tree - Zed Extension

A Zed editor extension that provides syntax highlighting for TODO-style comments and integrates with the todo-tree CLI via Zed's task system.

The CLI is maintained as a separate repository at todo-tree repository.

Check the original repository for more information.

Features

Syntax Highlighting

The extension provides syntax highlighting for TODO-style comments directly in your code editor. Tags like TODO, FIXME, BUG, HACK, NOTE, and others are highlighted with distinct colors, making them easy to spot while browsing your code.

This feature uses Tree-sitter for parsing and is based on the zed-comment extension's highlighting structure, with additional support for TODO-specific tags.

Customizing Colors

You can override the default highlight colors in your Zed theme. Refer to the zed-comment extension documentation for details on customizing theme colors for syntax highlighting.

Task Integration

The extension integrates with Zed's task system to run the todo-tree CLI. You can define tasks in your project's .zed/tasks.json or global tasks.json to scan for TODOs, view statistics, and more.

See TASKS.md for detailed documentation, examples, and best practices.

Prerequisites

This extension requires the todo-tree CLI to be installed on your system.

Installation

Install using Cargo:

cargo install todo-tree

After installation, verify it works:

tt --version
# or
todo-tree --version

Extension Installation

From Zed Extensions

1. Open Zed
2. Go to Extensions (Cmd+Shift+X on macOS)
3. Search for "Todo Tree"
4. Click Install

As a Dev Extension

For development or testing:

1. Clone the repository:

   git clone https://github.com/alexandretrotel/zed-todo-tree.git
   cd zed-todo-tree
   

2. In Zed, open the command palette (Cmd+Shift+P)

3. Run "zed: install dev extension"

4. Select the cloned directory

Usage

The extension works through Zed's task system. You can define tasks to scan for TODOs in your project.

For comprehensive task documentation, examples, and tips, see TASKS.md

Setting Up Tasks

Create a .zed/tasks.json file in your project root (or add to your global tasks with zed: open tasks):

[
  {
    "label": "List TODOs",
    "command": "tt",
    "args": ["scan", "$ZED_WORKTREE_ROOT"],
    "reveal": "always"
  },
  {
    "label": "List TODOs (JSON)",
    "command": "tt",
    "args": ["scan", "--json", "$ZED_WORKTREE_ROOT"],
    "reveal": "always"
  },
  {
    "label": "List TODOs by tag",
    "command": "tt",
    "args": ["scan", "$ZED_WORKTREE_ROOT", "--tags", "TODO,FIXME,BUG"],
    "reveal": "always"
  }
]

Running Tasks

1. Open the command palette (Cmd+Shift+P on macOS)
2. Type task: spawn and press Enter
3. Select one of your TODO tasks
4. The results will appear in a terminal panel

You can also bind tasks to keyboard shortcuts in your keymap.json:

{
  "context": "Workspace",
  "bindings": {
    "alt-t": ["task::Spawn", { "task_name": "List TODOs" }]
  }
}

Filtering by Tag

To filter by specific tags, use the --tags argument:

{
  "label": "List critical TODOs",
  "command": "tt",
  "args": ["scan", "$ZED_WORKTREE_ROOT", "--tags", "FIXME,BUG"]
}

Viewing Statistics

For a statistical summary, you can create a task that pipes the JSON output through a formatter, or simply review the JSON output from the --json flag.

Required Capabilities

The Todo Tree Zed extension requires certain capabilities that you may need to accept when first using it. Zed extensions operate under a capability system for security.

When prompted, you may need to grant the following permissions:

You can manage these permissions in your Zed settings under granted_extension_capabilities. Add the following to your settings.json:

{
  "granted_extension_capabilities": [
    {
      "kind": "process:exec",
      "command": "tt",
      "args": ["**"]
    },
    {
      "kind": "process:exec",
      "command": "todo-tree",
      "args": ["**"]
    },
  ]
}

If you restrict these capabilities, the extension may not function properly.

How It Works

The extension provides two main features:

1. Syntax Highlighting: Uses Tree-sitter to highlight TODO-style comments in your code with distinct colors
2. Task Integration: Grants capabilities for the todo-tree CLI (tt or todo-tree) to be executed through Zed's task system

When you run a task that calls the CLI:

1. Zed executes tt or todo-tree from your PATH
2. The CLI scans your project for TODO-style comments
3. Results are displayed in the terminal panel

The CLI respects .gitignore rules and supports many programming languages and comment styles.

Troubleshooting

"todo-tree CLI not found"

Make sure the CLI is installed and available in your PATH:

which tt
# or
which todo-tree

If installed via Cargo, ensure ~/.cargo/bin is in your PATH.

No TODOs Found

• Check that your files use standard comment syntax (//, #, /* */, etc.)
• Verify the tags are in uppercase (case-insensitive matching is enabled by default)
• Ensure the files aren't being ignored by .gitignore
• Verify the task is using the correct path (try using $ZED_WORKTREE_ROOT)

Tasks Not Working

• Ensure you've granted the extension permission to execute the CLI (see Required Capabilities section)
• Check that the CLI is installed and in your PATH
• Review the terminal output for error messages

Acknowledgments

• Tree-sitter grammar for comment parsing from tree-sitter-comment
• Syntax highlighting based on zed-comment - we re-used the same highlights.scm structure with additional tags support. For details about overriding theme colors for syntax highlighting, refer to the zed-comment extension.

Contributing

Contributions are welcome! Please see the zed-todo-tree repository for contribution guidelines.

License

MIT License - see LICENSE for details.