tdx

Your todos, in markdown, done fast.

<p align="center"> <img src="assets/demo-0.11.0.gif" alt="tdx demo" width="600"> </p>

A fast, single-binary CLI todo manager focused on developer experience. Features vim-style navigation, an interactive TUI, and scriptable commands—all stored in plain markdown you can version control.

Features

• ⚡ Fast - Single binary (4MB), instant startup, 30-40x faster than alternatives
• 📝 Markdown-native - Todos live in todo.md, version control friendly
• ⌨️ Vim-style navigation - j/k, relative jumps (5j), number keys
• 🖥️ Interactive TUI - Toggle, create, edit, delete, undo, move, copy
• 🎯 Command Palette - Helix-style : commands with fuzzy search
• 📋 Read-Only Mode - Prevent auto-save, check/uncheck all, filter done
• 🔧 Scriptable - list, add, toggle, edit, delete commands
• 🔄 Smart Conflict Detection - Auto-merge external changes, reactive file watching
• 📑 Per-File Configuration - YAML frontmatter for file-specific settings
• 📂 Recent Files - Jump to recently opened files with cursor position restoration
• 🌍 Cross-platform - macOS, Linux, Windows

Installation

Homebrew (macOS/Linux)

brew install niklas-heer/tap/tdx

Quick Install Script

curl -fsSL https://niklas-heer.github.io/tdx/install.sh | bash

Download Binary

Download the latest binary for your platform from Releases:

• tdx-darwin-arm64 - macOS Apple Silicon
• tdx-darwin-amd64 - macOS Intel
• tdx-linux-amd64 - Linux x64
• tdx-linux-arm64 - Linux ARM64
• tdx-windows-amd64.exe - Windows x64

From Source

Requires Go 1.25+:

git clone https://github.com/niklas-heer/tdx.git
cd tdx
just build
just install

Nix

# Try it without installing
nix run github:niklas-heer/tdx

# Install to profile
nix profile install github:niklas-heer/tdx

Usage

Interactive TUI (Default)

Launch the interactive todo manager:

tdx

Keyboard Shortcuts:

| Key | Action | |-----|--------| | j / k | Move down / up | | gg | Go to first item | | G | Go to last item | | Space / Enter | Toggle completion | | n | New todo after cursor | | N | New todo at end of file | | e | Edit todo | | d | Delete todo | | c | Copy to clipboard | | m | Move mode | | Tab | Indent (nest under previous) | | Shift+Tab | Outdent (move up one level) | | / | Fuzzy search | | t | Tag filter | | p | Priority filter | | D | Due date filter | | r | Recent files | | : | Command palette | | u | Undo | | ? | Help menu | | Esc | Quit | | Cmd+V / Ctrl+Y | Paste (in edit mode) |

Command Palette (:):

Press : to open the command palette with fuzzy search. Available commands:

| Command | Description | |---------|-------------| | check-all | Mark all todos as complete | | uncheck-all | Mark all todos as incomplete | | sort-done | Sort todos by completion (incomplete first) | | sort-priority | Sort todos by priority (p1 first, then p2, etc.) | | sort-due | Sort todos by due date (earliest first) | | filter-done | Toggle showing/hiding completed todos | | filter-due | Toggle showing only todos with due dates | | filter-overdue | Toggle showing only overdue todos | | filter-today | Toggle showing only todos due today | | filter-week | Toggle showing only todos due this week | | clear-done | Delete all completed todos | | read-only | Toggle read-only mode (changes not saved) | | save | Save current state to file | | force-save | Force save even if file was modified externally | | reload | Reload file from disk (discards unsaved changes) | | wrap | Toggle word wrap for long lines | | line-numbers | Toggle relative line numbers | | set-max-visible | Set max visible items for this session | | show-headings | Toggle displaying markdown headings between tasks |

Read-Only Mode:

Start tdx with -r or --read-only flag for workflows where you don't want changes saved automatically:

tdx -r checklist.md

Use :save to manually save when ready, or :read-only to turn auto-save back on.

Vim-style navigation:

• 5j - Move down 5 lines
• 3k - Move up 3 lines
• gg - Jump to first item
• G - Jump to last item

Fuzzy Search: Press / to enter search mode. Type to filter todos with live highlighting. Press Enter to select or Esc to cancel.

Nested Tasks:

Organize your todos hierarchically using Tab and Shift+Tab:

- [ ] Main project
  - [ ] Subtask 1
  - [ ] Subtask 2
    - [ ] Sub-subtask
- [ ] Another task

• Press Tab to indent a task under its previous sibling
• Press Shift+Tab to outdent (move up one level)
• Deleting a parent task promotes its children to the parent's level
• New tasks (n) are created at the same nesting level as the cursor

Tags & Filtering:

Add hashtags to your todos for organization:

- [ ] Fix authentication #urgent #backend
- [ ] Update docs #docs
- [ ] Add dark mode #feature #frontend

Press t to open tag filter mode:

• Navigate with ↑/↓ or j/k
• Toggle tags with Space or Enter
• Clear all filters with c
• Press Esc when done

Active tag filters are shown in the status bar. Todos are automatically filtered to show only matching items.

Priorities:

Add priority markers to your todos using !p1, !p2, !p3, etc.:

- [ ] Fix critical security bug !p1
- [ ] Update dependencies !p2
- [ ] Write documentation !p3
- [ ] Refactor code !p2
- [ ] Add nice-to-have feature

Priority levels:

• !p1 - Critical/Urgent (displayed in red)
• !p2 - High priority (displayed in orange)
• !p3 - Medium priority (displayed in yellow)
• !p4+ - Lower priorities (displayed dimmed)

Use the :sort-priority command to sort todos by priority (p1 first, then p2, etc.). Tasks without a priority marker are placed at the end. You can combine priorities with tags: Fix bug !p1 #backend #urgent

Priority Filtering:

Press p to open priority filter mode:

• Navigate with ↑/↓ or j/k
• Toggle priorities with Space or Enter
• Clear all filters with c
• Press Esc when done

Active priority filters are shown in the status bar (e.g., ⚡ p1 p2). You can combine priority and tag filters to narrow down your view.

Due Dates:

Add due dates to your todos using @due(YYYY-MM-DD):

- [ ] Submit quarterly report @due(2025-12-01)
- [ ] Review pull request @due(2025-11-30) #code-review
- [ ] Fix critical bug !p1 @due(2025-11-29) #urgent
- [ ] Plan team meeting @due(2025-12-15)

Due date display colors based on urgency:

• Overdue - Red (past the due date)
• Due today - Orange
• Due soon - Yellow (within 3 days)
• Future - Dimmed

Use the :sort-due command to sort todos by due date (earliest first). Tasks without a due date are placed at the end. You can combine due dates with priorities and tags.

Due Date Filtering:

Press D (capital D) to open due date filter mode:

• Overdue - Show only overdue tasks
• Today - Show tasks due today
• This Week - Show tasks due within 7 days
• Has Due Date - Show all tasks with any due date

Navigate with ↑/↓ or j/k, select with Space or Enter, clear with c, and press Esc when done.

Active due date filters are shown in the status bar (e.g., 📅 overdue). You can combine due date filters with priority and tag filters.

CLI Commands

# List all todos
tdx list

# Add a new todo
tdx add "Buy milk"

# Toggle completion (1-based index)
tdx toggle 1

# Edit a todo
tdx edit 2 "Updated text"

# Delete a todo
tdx delete 3

# Open most recent file
tdx last

# Use custom file
tdx ~/notes/work.md list
tdx project.md add "Task"

Recent Files

tdx automatically tracks recently opened files and restores your cursor position when you reopen them.

TUI Mode:

Press r in the TUI to open the recent files overlay:

• Type to filter files by path (fuzzy search)
• Navigate with ↑/↓ or j/k
• Press Enter to open a file
• Press Esc or r to close

CLI Commands:

# Open the most recently used file
tdx last

# List recently opened files (sorted by frequency and recency)
tdx recent

# Open a specific recent file by number
tdx recent 1

# Clear recent files history
tdx recent clear

Features:

• Smart Sorting: Files are ranked by both frequency (how often you open them) and recency (when you last accessed them)
• Cursor Restoration: When you reopen a file, tdx automatically restores your cursor to the last position
• Change Detection: If the file content has changed since your last visit, the cursor resets to the first item for safety
• Configurable Limit: Set maximum recent files in your config (default: 20)

Configuration:

In ~/.config/tdx/config.toml:

[recent]
max_files = 20  # Maximum number of recent files to track

Recent files are stored in ~/.config/tdx/recent.json and include:

• File path
• Last access time
• Access count (frequency)
• Last cursor position
• Content hash (for change detection)

File Format

Todos are stored in todo.md using standard Markdown:

# Todos

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

O