TODO Tracker

A Go tool that scans your codebase for @TT comments and converts them into organized task files. It supports two presentation modes — a simple CLI output and an interactive TUI — and can push tasks to version control issue trackers via pluggable backends (currently Forgejo).

Comment Format

Add comments anywhere in your source code:

// @TT name=task-name prio=100 description here
# @TT name=task-name prio=100 description here

Supported Styles

• // @TT and //@TT (with or without space after //) — for Go, Java, C, etc.
• # @TT and #@TT — for Python, Ruby, shell scripts, etc.
• name and prio values can contain letters, numbers, underscores, and hyphens.
• The description after prio is optional — everything after prio=value becomes the task comment.

Multi-line Comments

Append continuation lines for longer descriptions:

# @TT name=fix-this prio=1337
# I want to be able to have multi-line comments.
# So it should be able to read this as well.
# And this.

Ignore Files

Create a .todoignore file in the target directory to exclude files or directories from scanning. It uses a simple pattern format similar to .gitignore:

# Ignore generated files
*.log
*.tmp

# Ignore directories
vendor/
node_modules/

# Ignore specific files
*_helper.go
.env

Patterns ending with / match directories. Patterns with * are matched using glob rules.

Task Output

Tasks are created in a tasks/ directory, mirroring the source file structure. Each task file is named <prio>-<name>.task:

tasks/
├── 100-root.task
├── 82-hash-root.task
├── completed/                  # Archived tasks
│   └── 10-workflow-example.task
└── example/
    ├── 80-folder.task
    └── subfolder/
        └── 65-sub-folder.task

Each .task file contains:

Name: fix-bug
Prio: high
Comment: Description here
Source: path/to/source/file.go
Created at: 2026-10-14 23:23:00
Task ID: 953530160008

Completed tasks also include a Completed at timestamp.

Task Lifecycle

• Created/Updated: When a @TT comment exists in a source file, the corresponding task file is created or updated in tasks/. The Task ID and Created at timestamp are preserved across updates.
• Archived: When a @TT comment is removed from a source file, the task is automatically moved to tasks/completed/ with a Completed at timestamp.
• Pushed: todotracker push sends active tasks to a backend (e.g., Forgejo). Completed tasks are closed on the backend.

Usage

Presenters

Todotracker supports two presentation modes, selectable via the -presenter flag or the PRESENTER environment variable:

Presenter	Description
cli (default)	Simple stdout output — lists tasks and exits
tui	Interactive terminal UI with split-column layout, filtering, and inline actions

CLI Mode

# Scan and display tasks (default presenter: cli)
todotracker

# Scan a specific directory
todotracker -dir /path/to/project

# Use the TUI presenter
todotracker -presenter tui

TUI Mode

The TUI provides an interactive interface built with Bubbletea:

• Left column: Scrollable task list, sorted by priority (highest first)
• Right column: Detail view for the selected task (press Enter)
• Filtering: Use the list's built-in filter to search tasks

Keybindings:

Key	Action
q / Ctrl+C	Quit
Enter	Show task details in the right column
Esc	Clear detail view
s	Re-scan the target directory for changes
p	Push tasks to the configured backend
d	Mark the selected task as completed (remove from active list)
k	Toggle between active and completed tasks
↑ / ↓	Navigate the task list
/	Filter tasks

Push Command

Push active tasks to a backend and close completed ones:

# Using generic backend flags
todotracker push \
  -backend forgejo \
  -url https://git.example.com \
  -repo username/myrepo \
  -token YOUR_API_TOKEN \
  -labels todo,bug

# Legacy Forgejo flags (still supported)
todotracker push \
  -forgejo-url https://git.example.com \
  -forgejo-repo username/myrepo \
  -forgejo-token YOUR_API_TOKEN \
  -forgejo-labels todo,bug

The push command first scans and manages local tasks, then pushes active tasks to the backend. It uses the Task ID (derived from source + name + priority) to avoid creating duplicate issues. After pushing, it closes any issues whose tasks have been completed.

Environment Configuration

Create a .env file in your project root:

# Scanner
TODOTRACKER_DIR=.

# Presenter
PRESENTER=cli

# Backend (generic)
BACKEND=forgejo
URL=https://git.example.com
REPO=username/myrepo
TOKEN=your_token_here
LABELS=todo

# Legacy Forgejo-specific (auto-detected, sets BACKEND=forgejo)
FORGEJO_URL=https://git.example.com
FORGEJO_REPO=username/myrepo
FORGEJO_TOKEN=your_token_here
FORGEJO_LABELS=todo

CLI flags override .env values. The legacy FORGEJO_* variables are automatically detected and mapped to the generic backend settings.

Architecture

Todotracker uses a plugin-based architecture with two extensible interfaces:

Presenters

Presenters control how task information is displayed to the user. Built-in presenters:

• cli — Simple stdout output
• tui — Interactive terminal UI (Bubbletea)

Custom presenters can be registered via plugin.RegisterPresenter().

Backends

Backends handle pushing tasks to external issue trackers. Built-in backends:

• forgejo — Pushes tasks to a Forgejo/Gitea instance

Custom backends can be registered via plugin.RegisterBackend(). The Backend interface defines:

• PushTask(task, labels) — Create or update an issue; returns (issueNumber, wasCreated, error)
• CloseCompletedTasks(taskIDs) — Close issues for completed tasks
• Name() — Human-readable backend name

Installation

cd todotracker
go install ./cmd/

How It Works

1. Scan: Walks the target directory recursively, reading all files except .md, _test.go, and files matching .todoignore patterns.
2. Parse: Finds @TT comments and collects multi-line continuation lines.
3. Manage: Creates or updates .task files in tasks/, preserving Task ID and Created at timestamps. Tasks whose source comment was removed are moved to tasks/completed/.
4. Display: The selected presenter (CLI or TUI) shows the task list.
5. Push (optional): todotracker push sends active tasks to a backend and closes completed ones, using Task ID to avoid duplicates.