tuxedo

A fast, keyboard-driven terminal UI for todo.txt. Vim-style bindings, atomic writes, instant external-edit detection, and five hand-tuned themes — all in a single static binary.

brew install tuxedo

For a more in-depth walkthrough, please watch this video by @IogaMaster.

Highlights

• Pure todo.txt. Reads and writes the standard format — every line is plain text you can edit with anything else.
• TUI and CLI in one binary. Run tuxedo for the interactive UI, or tuxedo <command> for a todo.txt-cli-compatible command line (add, ls, do, pri, archive, …) — scriptable, with --json output and $TODO_DIR / $TODO_FILE / $DONE_FILE support.
• Natural-language add. Type prose into the add prompt — Pay rent monthly on the first, show 3 days before due, project home — and tuxedo rewrites it to canonical todo.txt for you to review and save. Local, offline, no AI service.
• Phone capture. Press s for a QR pointing at a tiny PWA on your machine's LAN — type tasks from your phone and they appear in the list. Captures land in a sibling inbox.txt first, so any tool that can append a line (shell, iOS Shortcuts, cron) is also a capture source.
• Vim keys, no surprises. j / k to move, dd to delete, gg / G to jump, u to undo (50 levels), chord prompts (gg, dd, fp, fc) with a 600 ms window.
• Command palette. : or Ctrl-P opens a fuzzy palette over every action — type a few letters, hit Enter. Same matcher as / search, ranked so start-of-label hits beat word-boundary hits beat mid-word hits.
• Atomic, sync-friendly writes. Every change goes through write-temp-then-rename. If another process — Dropbox, an editor, a script — modifies the file, tuxedo reloads on the next keypress (or within ~250 ms while idle) and flashes a notice.
• Sibling-file archive. A moves completed tasks to done.txt next to your file, atomically.
• Filter, sort, multi-select. Cycle by +project or @context, sort by priority / due / file order, and bulk-complete or bulk-delete in visual mode.
• Saved searches. Name the active /-search with fs, then recall it any time by cycling saved filters with ff. Stored as plain filter.<name> lines in the config — hand-editable like everything else.
• Five themes, three densities. Cycle with T and D. Choices persist across runs.
• No daemon, no database, no cloud. One file in, one file out.

Screens

Empty state • cell-bowtie mark and quick-start when the file has no tasks
List • list of todos, optionally grouped
Archive • completed tasks grouped by completion date
Filter sidebar active • fp cycles projects with j/k, fc cycles contexts; saved searches list under a SAVED heading with live match counts
Command palette • : or Ctrl-P opens a fuzzy palette over every action
Help • ? opens the full keybindings overlay

The screenshots in the table above are checked-in SVGs. Regenerate them with:

mise run screenshots

The hero GIF at the top is recorded with vhs from docs/demo.tape. Regenerate it with:

mise run demo

Themes

T opens a picker over five built-in themes, including Terminal, which respects your terminal palette.

Muted Slate (default)	Dawn
Nord	Matrix

Custom themes

Beyond the built-ins, tuxedo loads any *.toml file you drop in ${XDG_CONFIG_HOME:-$HOME/.config}/tuxedo/themes/. Each one joins the T picker in sorted filename order. Ready-made themes live in docs/themes/ — copy one in and press T:

mkdir -p ~/.config/tuxedo/themes
curl -o ~/.config/tuxedo/themes/gruvbox-dark-soft.toml \
  https://raw.githubusercontent.com/webstonehq/tuxedo/main/docs/themes/gruvbox-dark-soft.toml

A theme file is one key = value per line. name is the label shown in the picker; every other field is a color value. All fields are required: a file missing one, carrying an unparseable color, or whose name collides with another theme is skipped with a warning at startup.

Color values accept two forms:

• #rrggbb — a solid hex color (case-insensitive).
• reset or transparent — inherits the terminal emulator's own background color. Useful for bg, panel, and statusbar when you want your terminal's opacity, blur, or wallpaper to show through while keeping a custom text palette. Both keywords are case-insensitive and behave identically (same effect as the built-in Terminal theme).

Install

Homebrew (macOS, Linux)

brew install tuxedo

Prebuilt binaries

Download the archive for your platform from the latest release and put tuxedo on your PATH.

Targets: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-apple-darwin, aarch64-apple-darwin, x86_64-pc-windows-msvc. Each archive ships with a .sha256 checksum.

From source

cargo install --git https://github.com/webstonehq/tuxedo

Or clone and build:

git clone https://github.com/webstonehq/tuxedo
cd tuxedo
cargo build --release
./target/release/tuxedo [FILE]

Requires the Rust 2024 edition (recent stable toolchain).

Usage

tuxedo is two things in one binary: an interactive TUI, and a one-shot command line. With no subcommand it launches the TUI; with a recognized subcommand it runs the command line and exits.

tuxedo [FILE]      # launch the TUI on FILE (created if missing)
tuxedo             # TUI on the default file (see resolution below)
tuxedo --sample    # open the bundled sample file in the temp dir
tuxedo <command>   # run a one-shot CLI command — see "Command-line interface"
tuxedo update      # print upgrade instructions for your install
tuxedo --help
tuxedo --version

When a newer release is available, the status bar shows ↑ <version> (tuxedo update) next to the version. The check runs in the background, is cached at $XDG_CACHE_HOME/tuxedo/latest_version.json for 24 h, and fails silently when offline. Set TUXEDO_NO_UPDATE_CHECK=1 to disable.

Which file tuxedo opens

Both the TUI and the CLI resolve the todo file the same way, in order:

1. An explicit FILE argument (TUI only).
2. $TODO_FILE, if set.
3. $TODO_DIR/todo.txt, if $TODO_DIR is set.
4. ./todo.txt in the current directory, if it exists.
5. Otherwise the TUI shows a first-run prompt — press c to create ./todo.txt here, or s to open a sample todo.txt in the system temp directory so you can poke around without committing to a path. (The one-shot CLI is non-interactive and uses the sample directly.)

The archive file is $DONE_FILE if set, otherwise a sibling done.txt next to the todo file. The file (and any missing parent directories) is created on first use. These are the same TODO_DIR / TODO_FILE / DONE_FILE variables todo.txt-cli uses, so an existing todo.cfg works as-is:

export TODO_DIR="$HOME/Documents/todo"
export TODO_FILE="$TODO_DIR/todo.txt"
export DONE_FILE="$TODO_DIR/done.txt"

Edits are persisted on every change via atomic write (write .tmp, rename).

If the file changes on disk (another editor, a sync client, a script), tuxedo notices on the next keypress, or within ~250 ms while idle, and reloads. The keystroke that triggered the reload is consumed — press it again to act on the fresh state — and the status bar flashes a notice.

Pressing A appends every completed task to a sibling done.txt and removes them from the working file (atomically: done.txt is written before the originals are dropped). a toggles the archive view so you can browse, un-archive, or permanently delete past tasks.

Command-line interface

When the first argument is a recognized subcommand, tuxedo runs a one-shot command instead of launching the TUI. The surface mirrors todo.txt-cli — same commands, aliases, task numbering, and output — so it's a drop-in for scripts and aliases.

tuxedo add "Pay rent +home @bank due:2026-07-01"   # or: tuxedo a "..."
tuxedo ls @bank                                     # filter by context
tuxedo do 3                                          # mark task 3 complete
tuxedo pri 3 A                                        # set priority
tuxedo archive                                        # move done tasks to done.txt
tuxedo ls --json | jq .                              # machine-readable output

Task numbers are 1-based line numbers in the file, exactly as printed by list — stable regardless of how the list is filtered or sorted. list sorts by the full line (case-insensitive) and prints a TODO: X of Y tasks shown footer, matching todo.txt-cli.

Options:

• -f, --force — skip confirmation prompts (e.g. for del).
• --json — emit machine-readable JSON instead of text. list-style commands print an array of task objects; mutating commands print a result object. No prompts or footers are written in this mode.

Global flags may appear before the subcommand (tuxedo -f del 3).

Differences from todo.txt-cli: do marks a task complete but does not auto-archive it — completed tasks stay in the file until you run archive (or press A in the TUI), matching tuxedo's interactive model. There is no -d config-file flag; configure paths with the environment variables above.

Keybindings

Custom normal-mode keybindings can be added in ${XDG_CONFIG_HOME:-$HOME/.config}/tuxedo/keybinds.toml:

The block below lists every rebindable action with the key it ships with — copy it, then change the keys you care about and delete the rest (anything you leave out keeps its default). A value is a single key or an array of alternatives, e.g. begin_add = ["N", "Ctrl-n"].

[normal]

# Navigation
cursor_down    = ["j", "Down"]
cursor_up      = ["k", "Up"]
cursor_top     = "gg"
cursor_bottom  = "G"
half_page_down = "Ctrl-d"
half_page_up   = "Ctrl-u"

# Editing
begin_add            = "n"
begin_edit           = "e"
begin_edit_insert    = "i"
toggle_complete      = "x"
delete               = "dd"
reschedule           = "r"
cycle_priority       = "p"
begin_prompt_context = "c"
copy_line            = "yy"
copy_body            = "yb"
undo                 = "u"
# begin_prompt_project defaults to "+", which can't be written here (the
# parser reads "+" as a modifier separator). Pick another key to move it, e.g.
# begin_prompt_project = "P"

# Filtering, sort, view
begin_search        = "/"
arm_f               = "f"        # leader for the fp / fc / ff / fs chords
pick_project        = "fp"
pick_context        = "fc"
pick_saved_filter   = "ff"
save_current_filter = "fs"
cycle_sort          = "S"
toggle_visual       = "v"
toggle_selected     = "space"
go_list             = "l"
toggle_archive_view = "a"
archive_completed   = "A"
toggle_show_done    = "H"
toggle_show_future  = "F"

# Layout & theme
toggle_left_pane  = "["
toggle_right_pane = "]"
open_theme_picker = "T"
cycle_density     = "D"
toggle_line_num   = "L"
# cycle_theme has no default — bind a key to cycle themes without the picker:
# cycle_theme = "Ctrl-t"

# System
open_command_palette = [":", "Ctrl-P"]
open_share           = "s"
open_help            = "?"
open_settings        = ","
escape_stack         = "Esc"
quit                 = "q"

Custom bindings are checke