{"id":33597838,"url":"https://github.com/niklas-heer/tdx","last_synced_at":"2026-06-29T15:31:19.057Z","repository":{"id":325535885,"uuid":"1101294122","full_name":"niklas-heer/tdx","owner":"niklas-heer","description":"tdx - your todos, in markdown, done fast.","archived":false,"fork":false,"pushed_at":"2025-12-02T18:40:13.000Z","size":35664,"stargazers_count":52,"open_issues_count":2,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-24T05:42:30.324Z","etag":null,"topics":["cli","command-line","git","go","golang","justfile","markdown","productivity","task-manager","todo-list","todoapp","todolist","tui"],"latest_commit_sha":null,"homepage":"https://niklas-heer.github.io/tdx/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niklas-heer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-21T13:25:14.000Z","updated_at":"2026-04-13T12:54:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/niklas-heer/tdx","commit_stats":null,"previous_names":["niklas-heer/tdx"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/niklas-heer/tdx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niklas-heer%2Ftdx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niklas-heer%2Ftdx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niklas-heer%2Ftdx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niklas-heer%2Ftdx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niklas-heer","download_url":"https://codeload.github.com/niklas-heer/tdx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niklas-heer%2Ftdx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34933498,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line","git","go","golang","justfile","markdown","productivity","task-manager","todo-list","todoapp","todolist","tui"],"created_at":"2025-11-30T03:08:47.726Z","updated_at":"2026-06-29T15:31:19.032Z","avatar_url":"https://github.com/niklas-heer.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tdx\n\n[![CI](https://github.com/niklas-heer/tdx/actions/workflows/ci.yml/badge.svg)](https://github.com/niklas-heer/tdx/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/niklas-heer/tdx/main/.github/badges/coverage.json)](https://github.com/niklas-heer/tdx/actions/workflows/ci.yml)\n[![GitHub Downloads](https://img.shields.io/github/downloads/niklas-heer/tdx/total?logo=github\u0026label=downloads)](https://github.com/niklas-heer/tdx/releases)\n[![Go Report Card](https://goreportcard.com/badge/github.com/niklas-heer/tdx)](https://goreportcard.com/report/github.com/niklas-heer/tdx)\n\n**Your todos, in markdown, done fast.**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo-0.11.0.gif\" alt=\"tdx demo\" width=\"600\"\u003e\n\u003c/p\u003e\n\nA 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.\n\n## Features\n\n- ⚡ **Fast** - Single binary (4MB), instant startup, 30-40x faster than alternatives\n- 📝 **Markdown-native** - Todos live in `todo.md`, version control friendly\n- ⌨️ **Vim-style navigation** - `j/k`, relative jumps (`5j`), number keys\n- 🖥️ **Interactive TUI** - Toggle, create, edit, delete, undo, move, copy\n- 🎯 **Command Palette** - Helix-style `:` commands with fuzzy search\n- 📋 **Read-Only Mode** - Prevent auto-save, check/uncheck all, filter done\n- 🔧 **Scriptable** - `list`, `add`, `toggle`, `edit`, `delete` commands\n- 🔄 **Smart Conflict Detection** - Auto-merge external changes, reactive file watching\n- 📑 **Per-File Configuration** - YAML frontmatter for file-specific settings\n- 📂 **Recent Files** - Jump to recently opened files with cursor position restoration\n- 🌍 **Cross-platform** - macOS, Linux, Windows\n\n## Installation\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew install niklas-heer/tap/tdx\n```\n\n### Quick Install Script\n\n```bash\ncurl -fsSL https://niklas-heer.github.io/tdx/install.sh | bash\n```\n\n### Download Binary\n\nDownload the latest binary for your platform from [Releases](https://github.com/niklas-heer/tdx/releases):\n\n- `tdx-darwin-arm64` - macOS Apple Silicon\n- `tdx-darwin-amd64` - macOS Intel\n- `tdx-linux-amd64` - Linux x64\n- `tdx-linux-arm64` - Linux ARM64\n- `tdx-windows-amd64.exe` - Windows x64\n\n### From Source\n\nRequires Go 1.25+:\n\n```bash\ngit clone https://github.com/niklas-heer/tdx.git\ncd tdx\njust build\njust install\n```\n\n### Nix\n\n```bash\n# Try it without installing\nnix run github:niklas-heer/tdx\n\n# Install to profile\nnix profile install github:niklas-heer/tdx\n```\n\n## Usage\n\n### Interactive TUI (Default)\n\nLaunch the interactive todo manager:\n\n```bash\ntdx\n```\n\n**Keyboard Shortcuts:**\n\n| Key | Action |\n|-----|--------|\n| `j` / `k` | Move down / up |\n| `gg` | Go to first item |\n| `G` | Go to last item |\n| `Space` / `Enter` | Toggle completion |\n| `n` | New todo after cursor |\n| `N` | New todo at end of file |\n| `e` | Edit todo |\n| `d` | Delete todo |\n| `c` | Copy to clipboard |\n| `m` | Move mode |\n| `Tab` | Indent (nest under previous) |\n| `Shift+Tab` | Outdent (move up one level) |\n| `/` | Fuzzy search |\n| `t` | Tag filter |\n| `p` | Priority filter |\n| `D` | Due date filter |\n| `r` | Recent files |\n| `:` | Command palette |\n| `u` | Undo |\n| `?` | Help menu |\n| `Esc` | Quit |\n| `Cmd+V` / `Ctrl+Y` | Paste (in edit mode) |\n\n**Command Palette (`:`):**\n\nPress `:` to open the command palette with fuzzy search. Available commands:\n\n| Command | Description |\n|---------|-------------|\n| `check-all` | Mark all todos as complete |\n| `uncheck-all` | Mark all todos as incomplete |\n| `sort-done` | Sort todos by completion (incomplete first) |\n| `sort-priority` | Sort todos by priority (p1 first, then p2, etc.) |\n| `sort-due` | Sort todos by due date (earliest first) |\n| `filter-done` | Toggle showing/hiding completed todos |\n| `filter-due` | Toggle showing only todos with due dates |\n| `filter-overdue` | Toggle showing only overdue todos |\n| `filter-today` | Toggle showing only todos due today |\n| `filter-week` | Toggle showing only todos due this week |\n| `clear-done` | Delete all completed todos |\n| `read-only` | Toggle read-only mode (changes not saved) |\n| `save` | Save current state to file |\n| `force-save` | Force save even if file was modified externally |\n| `reload` | Reload file from disk (discards unsaved changes) |\n| `wrap` | Toggle word wrap for long lines |\n| `line-numbers` | Toggle relative line numbers |\n| `set-max-visible` | Set max visible items for this session |\n| `show-headings` | Toggle displaying markdown headings between tasks |\n\n**Read-Only Mode:**\n\nStart tdx with `-r` or `--read-only` flag for workflows where you don't want changes saved automatically:\n\n```bash\ntdx -r checklist.md\n```\n\nUse `:save` to manually save when ready, or `:read-only` to turn auto-save back on.\n\n**Vim-style navigation:**\n- `5j` - Move down 5 lines\n- `3k` - Move up 3 lines\n- `gg` - Jump to first item\n- `G` - Jump to last item\n\n**Fuzzy Search:**\nPress `/` to enter search mode. Type to filter todos with live highlighting. Press `Enter` to select or `Esc` to cancel.\n\n**Nested Tasks:**\n\nOrganize your todos hierarchically using `Tab` and `Shift+Tab`:\n\n```markdown\n- [ ] Main project\n  - [ ] Subtask 1\n  - [ ] Subtask 2\n    - [ ] Sub-subtask\n- [ ] Another task\n```\n\n- Press `Tab` to indent a task under its previous sibling\n- Press `Shift+Tab` to outdent (move up one level)\n- Deleting a parent task promotes its children to the parent's level\n- New tasks (`n`) are created at the same nesting level as the cursor\n\n**Tags \u0026 Filtering:**\n\nAdd hashtags to your todos for organization:\n\n```markdown\n- [ ] Fix authentication #urgent #backend\n- [ ] Update docs #docs\n- [ ] Add dark mode #feature #frontend\n```\n\nPress `t` to open tag filter mode:\n- Navigate with `↑/↓` or `j/k`\n- Toggle tags with `Space` or `Enter`\n- Clear all filters with `c`\n- Press `Esc` when done\n\nActive tag filters are shown in the status bar. Todos are automatically filtered to show only matching items.\n\n**Priorities:**\n\nAdd priority markers to your todos using `!p1`, `!p2`, `!p3`, etc.:\n\n```markdown\n- [ ] Fix critical security bug !p1\n- [ ] Update dependencies !p2\n- [ ] Write documentation !p3\n- [ ] Refactor code !p2\n- [ ] Add nice-to-have feature\n```\n\nPriority levels:\n- `!p1` - Critical/Urgent (displayed in red)\n- `!p2` - High priority (displayed in orange)\n- `!p3` - Medium priority (displayed in yellow)\n- `!p4+` - Lower priorities (displayed dimmed)\n\nUse 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`\n\n**Priority Filtering:**\n\nPress `p` to open priority filter mode:\n- Navigate with `↑/↓` or `j/k`\n- Toggle priorities with `Space` or `Enter`\n- Clear all filters with `c`\n- Press `Esc` when done\n\nActive priority filters are shown in the status bar (e.g., `⚡ p1 p2`). You can combine priority and tag filters to narrow down your view.\n\n**Due Dates:**\n\nAdd due dates to your todos using `@due(YYYY-MM-DD)`:\n\n```markdown\n- [ ] Submit quarterly report @due(2025-12-01)\n- [ ] Review pull request @due(2025-11-30) #code-review\n- [ ] Fix critical bug !p1 @due(2025-11-29) #urgent\n- [ ] Plan team meeting @due(2025-12-15)\n```\n\nDue date display colors based on urgency:\n- **Overdue** - Red (past the due date)\n- **Due today** - Orange\n- **Due soon** - Yellow (within 3 days)\n- **Future** - Dimmed\n\nUse 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.\n\n**Due Date Filtering:**\n\nPress `D` (capital D) to open due date filter mode:\n- **Overdue** - Show only overdue tasks\n- **Today** - Show tasks due today\n- **This Week** - Show tasks due within 7 days\n- **Has Due Date** - Show all tasks with any due date\n\nNavigate with `↑/↓` or `j/k`, select with `Space` or `Enter`, clear with `c`, and press `Esc` when done.\n\nActive due date filters are shown in the status bar (e.g., `📅 overdue`). You can combine due date filters with priority and tag filters.\n\n### CLI Commands\n\n```bash\n# List all todos\ntdx list\n\n# Add a new todo\ntdx add \"Buy milk\"\n\n# Toggle completion (1-based index)\ntdx toggle 1\n\n# Edit a todo\ntdx edit 2 \"Updated text\"\n\n# Delete a todo\ntdx delete 3\n\n# Open most recent file\ntdx last\n\n# Use custom file\ntdx ~/notes/work.md list\ntdx project.md add \"Task\"\n```\n\n### Recent Files\n\ntdx automatically tracks recently opened files and restores your cursor position when you reopen them.\n\n**TUI Mode:**\n\nPress `r` in the TUI to open the recent files overlay:\n- Type to filter files by path (fuzzy search)\n- Navigate with `↑/↓` or `j/k`\n- Press `Enter` to open a file\n- Press `Esc` or `r` to close\n\n**CLI Commands:**\n\n```bash\n# Open the most recently used file\ntdx last\n\n# List recently opened files (sorted by frequency and recency)\ntdx recent\n\n# Open a specific recent file by number\ntdx recent 1\n\n# Clear recent files history\ntdx recent clear\n```\n\n**Features:**\n- **Smart Sorting**: Files are ranked by both frequency (how often you open them) and recency (when you last accessed them)\n- **Cursor Restoration**: When you reopen a file, tdx automatically restores your cursor to the last position\n- **Change Detection**: If the file content has changed since your last visit, the cursor resets to the first item for safety\n- **Configurable Limit**: Set maximum recent files in your config (default: 20)\n\n**Configuration:**\n\nIn `~/.config/tdx/config.toml`:\n\n```toml\n[recent]\nmax_files = 20  # Maximum number of recent files to track\n```\n\nRecent files are stored in `~/.config/tdx/recent.json` and include:\n- File path\n- Last access time\n- Access count (frequency)\n- Last cursor position\n- Content hash (for change detection)\n\n## File Format\n\nTodos are stored in `todo.md` using standard Markdown:\n\n```markdown\n# Todos\n\n- [x] Completed task\n- [ ] Incomplete task\n- [ ] Another task\n\nOther markdown content is preserved.\n```\n\n### Configuration\n\ntdx supports three levels of configuration with the following priority:\n\n**Priority Order:** CLI flags \u003e Frontmatter \u003e Global config \u003e Defaults\n\n#### Global Configuration\n\nCreate `~/.config/tdx/config.toml` (or `$XDG_CONFIG_HOME/tdx/config.toml`) to set defaults:\n\n```toml\n[theme]\nname = \"tokyo-night\"\n\n[display]\ncheck_symbol = \"✓\"\nselect_marker = \"➜\"\n\n[defaults]\nfile = \"todo.md\"      # default file (use ~/path for central file)\nmax_visible = 0       # 0 = unlimited\nword_wrap = true\nshow_headings = false\nread_only = false\nfilter_done = false\n\n[recent]\nmax_files = 20\n```\n\nYou only need to include the settings you want to change from the defaults.\n\n**Available options:**\n\n| Section | Option | Type | Default | Description |\n|---------|--------|------|---------|-------------|\n| `[theme]` | `name` | string | \"tokyo-night\" | Theme to use |\n| `[display]` | `check_symbol` | string | \"✓\" | Symbol for completed items |\n| `[display]` | `select_marker` | string | \"➜\" | Symbol for selected item |\n| `[defaults]` | `file` | string | \"todo.md\" | Default file path (use `~/path` for central file) |\n| `[defaults]` | `max_visible` | number | 0 | Limit visible tasks (0 = unlimited) |\n| `[defaults]` | `word_wrap` | boolean | true | Enable word wrapping for long lines |\n| `[defaults]` | `show_headings` | boolean | false | Show markdown headings between tasks |\n| `[defaults]` | `read_only` | boolean | false | Prevent all edits (view-only mode) |\n| `[defaults]` | `filter_done` | boolean | false | Hide completed tasks by default |\n| `[recent]` | `max_files` | number | 20 | Maximum recent files to track |\n\n#### Per-File Configuration\n\nAdd YAML frontmatter to customize behavior for specific files:\n\n```markdown\n---\nread-only: false\nmax-visible: 10\nshow-headings: true\n---\n# Todos\n\n- [ ] Task one\n```\n\n**Examples:**\n\nRead-only checklist:\n```markdown\n---\nread-only: true\n---\n# Shopping List\n- [ ] Milk\n```\n\nProject tracker with headings:\n```markdown\n---\nshow-headings: true\nmax-visible: 15\nfilter-done: true\n---\n# Project Tasks\n\n## Backend\n- [ ] API endpoints\n\n## Frontend\n- [ ] UI components\n```\n\n#### Configuration Priority\n\nSettings are applied in this order (highest to lowest priority):\n\n1. **CLI flags** - `tdx -r --show-headings todo.md`\n2. **Frontmatter** - YAML at top of individual todo files\n3. **Global config** - `~/.config/tdx/config.toml`\n4. **Defaults** - Built-in defaults (word_wrap: true, others: false/0)\n\n**Example:**\n```bash\n# config.toml sets word_wrap = false\n# Frontmatter sets read-only: true\n# CLI flag: --show-headings\n# Result: word_wrap=false, read_only=true, show_headings=true\ntdx --show-headings todo.md\n```\n\n## Architecture\n\n### AST-Based Markdown Engine\n\ntdx uses **[Goldmark](https://github.com/yuin/goldmark)** (Go's industry-standard Markdown parser) with a custom serializer to provide robust, format-preserving todo management:\n\n**Why AST over regex?**\n- ⚡ **Performance** - Parse once, manipulate efficiently in memory\n- 🎯 **Precision** - Surgical updates to specific nodes without side effects\n- 📝 **Format Preservation** - Maintains your markdown structure, spacing, and formatting\n- 🔒 **Reliability** - Correctly handles edge cases (nested lists, code blocks, links, etc.)\n- 🏷️ **Rich Features** - Enables advanced features like tag extraction, heading tracking\n\n**How it works:**\n\n```\nRead File → Goldmark Parser → AST (in-memory tree)\n                                  ↓\n                           Manipulate nodes\n                           (toggle, add, delete, swap)\n                                  ↓\n                          Custom Serializer → Write File\n```\n\n**Implementation Details:**\n\n1. **Parser** (`internal/markdown/ast.go:29`)\n   - Uses **Goldmark** with GitHub Flavored Markdown (GFM) extension\n   - Parses markdown into an Abstract Syntax Tree\n   - Each todo becomes a `TaskCheckBox` node within a `ListItem`\n   - Preserves source bytes with segment pointers for text nodes\n\n2. **AST Operations** (`internal/markdown/ast.go`)\n   - `ExtractTodos()` - Walk AST and collect all task list items\n   - `ExtractHeadings()` - Find headings and their positions relative to todos\n   - `ToggleTodo()` - Flip checkbox state in the AST\n   - `UpdateTodoText()` - Append new text to source, update segment pointers\n   - `DeleteTodo()` - Remove list item node from parent\n   - `AddTodo()` - Create new list item with checkbox and text nodes\n   - `SwapTodos()` - Reorder list items (handles adjacent and cross-section swaps)\n\n3. **Custom Serializer** (`internal/markdown/serializer.go:12`)\n   - Recursively walks the modified AST\n   - Reconstructs markdown with proper formatting\n   - Built custom because Goldmark's renderer had formatting issues\n   - Handles: headings, lists, checkboxes, code blocks, links, emphasis, strikethrough, etc.\n   - Preserves spacing and blank lines\n\n**Key Benefits:**\n\n- ✅ **Non-destructive** - Your markdown formatting, comments, and structure stay intact\n- ✅ **Complex markdown** - Handles nested lists, code blocks, links, emphasis seamlessly\n- ✅ **Fast operations** - No regex scanning, no full-file rewrites\n- ✅ **Predictable** - AST guarantees correct parsing and serialization\n- ✅ **Tag support** - HashtagExtraction built into AST traversal\n- ✅ **Heading-aware** - Knows which todos belong under which headings\n\n### Performance Optimizations\n\ntdx is built for speed with several key optimizations:\n\n- **Search debouncing** - Search operations are debounced (50ms) to avoid scoring all todos on every keystroke\n- **Heading caching** - Heading positions are cached and only recomputed when todos change\n- **Zero-allocation navigation** - Finding next/previous visible items allocates no memory (~8ns)\n- **Unified input handling** - TUI and piped input share the same handlers, reducing code and bugs\n\n**Benchmark results** (Apple M4):\n```\nFuzzyScore (exact match):     5.6ns/op    0 allocs\nFuzzyScore (fuzzy match):    33.4ns/op    0 allocs\nCached headings:              1.0ns/op    0 allocs\nSearch 100 todos:             9.8µs/op  114 allocs\nNavigation (visible todo):    8.0ns/op    0 allocs\n```\n\n### Project Structure\n\n```\ntdx/\n├── cmd/tdx/              # Main application\n│   ├── main.go          # Entry point, CLI routing\n│   ├── config.go        # Build-time configuration\n│   ├── userconfig.go    # User configuration (themes, settings)\n│   └── *_test.go        # Comprehensive test suite\n├── internal/\n│   ├── markdown/        # AST-based markdown engine\n│   │   ├── parser.go    # Markdown → AST\n│   │   ├── ast.go       # AST data structures\n│   │   └── serializer.go # AST → Markdown\n│   ├── tui/             # Terminal UI (Bubble Tea)\n│   │   ├── model.go     # Application state\n│   │   ├── update.go    # Event handling\n│   │   ├── view.go      # Rendering\n│   │   ├── commands.go  # Command palette\n│   │   ├── render.go    # Display logic\n│   │   └── *_test.go    # Unit \u0026 benchmark tests\n│   ├── cmd/             # CLI command handlers\n│   │   └── cli.go       # List, add, toggle, etc.\n│   ├── config/          # Configuration handling\n│   │   ├── config.go    # Legacy YAML config (deprecated)\n│   │   └── recent.go    # Recent files tracking\n│   └── util/            # Utilities\n│       ├── text.go      # Text processing, fuzzy search\n│       ├── clipboard.go # Clipboard operations\n│       └── text_test.go # Unit \u0026 benchmark tests\n└── scripts/             # Development \u0026 release tools\n```\n\n## Development\n\n### Prerequisites\n\n- Go 1.25+\n- [just](https://github.com/casey/just) (command runner)\n\n### Building\n\n```bash\n# Build binary\njust build\n\n# Build for all platforms\njust build-all\n\n# Install to /usr/local/bin\njust install\n```\n\n### Commands\n\n```bash\njust build      # Build binary\njust install    # Install to PATH\njust tui        # Run TUI\njust list       # List todos\njust add \"X\"    # Add todo\njust toggle 1   # Toggle todo\njust check      # Run go vet\njust fmt        # Format code\njust clean      # Clean artifacts\n```\n\n## Theme Customization\n\n### Theme Picker\n\nPress `:` to open the command palette and select `theme` to open the theme picker:\n- Navigate with `↑/↓` or `j/k` to preview themes in real-time\n- Press `Enter` to apply and save the theme\n- Press `Esc` to cancel and restore the previous theme\n\nThe selected theme is automatically saved to your config file.\n\n### Theme Config File\n\nSet your theme in `~/.config/tdx/config.toml`:\n\n```toml\n[theme]\nname = \"tokyo-night\"  # or any builtin/custom theme\n```\n\nSee the [Global Configuration](#global-configuration) section for all available settings.\n\n### Builtin Themes\n\n- `tokyo-night` (default)\n- `catppuccin-latte` (light)\n- `catppuccin-frappe`\n- `catppuccin-macchiato`\n- `catppuccin-mocha`\n- `dracula`\n- `github-dark`\n- `gruvbox-dark`\n- `monokai`\n- `nord`\n- `one-dark`\n- `rose-pine`\n- `solarized-dark`\n\n### Custom Themes\n\nCreate your own themes by adding `.toml` files to `~/.config/tdx/themes/`:\n\n```toml\n# ~/.config/tdx/themes/my-theme.toml\n[theme]\nname = \"my-theme\"\nauthor = \"Your Name\"\n\n[colors]\n# Core colors\nBase = \"#c0caf5\"       # default foreground\nDim = \"#565f89\"        # muted text\nAccent = \"#7aa2f7\"     # highlights, selections\nSuccess = \"#9ece6a\"    # completed items, matches\nWarning = \"#e0af68\"    # move mode\nImportant = \"#bb9af7\"  # checked items\nAlertError = \"#f7768e\" # errors\n\n# Tags (hashtags like #urgent)\nTag = \"#e0af68\"\n\n# Priorities (!p1, !p2, !p3+)\nPriorityHigh = \"#f7768e\"    # !p1 - critical\nPriorityMedium = \"#bb9af7\"  # !p2 - high\nPriorityLow = \"#565f89\"     # !p3+ - medium/low\n\n# Due dates (@due(YYYY-MM-DD))\nDueUrgent = \"#7dcfff\"  # overdue or due today\nDueSoon = \"#7aa2f7\"    # due within 3 days\nDueFuture = \"#565f89\"  # due later\n```\n\nCustom themes appear in the theme picker alongside builtin themes. You can also override builtin themes by creating a file with the same theme name.\n\n**Note:** The Tag, Priority*, and Due* colors are optional. If omitted, sensible defaults are used based on the core colors.\n\n### Custom File Path\n\n```bash\ntdx ~/notes/work.md           # Use specific file\ntdx project.md add \"Task\"     # All commands work\n```\n\n### Build Configuration\n\nBuild metadata in `tdx.toml`:\n```toml\nversion = \"0.6.0\"\ndescription = \"your todos, in markdown, done fast\"\n```\n\n## License\n\nMIT - see [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniklas-heer%2Ftdx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniklas-heer%2Ftdx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniklas-heer%2Ftdx/lists"}