Kairos
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.
Timeline
6 Months
Role
Systems Developer
Team
Solo
Status
ActiveTechnology Stack
Key Challenges
- Implementing atomic file writes that stay safe under concurrent editors, sync tools, and scripts
- Detecting external file changes within ~250 ms while idle without polling overhead
- Building natural-language task parsing that runs fully offline without any AI service
- Designing a phone capture flow — QR code, LAN PWA, inbox.txt — that works without a cloud dependency
- Supporting Vim-style chord sequences (gg, dd, fp, fc) with a clean 600 ms window and no input ambiguity
Key Learnings
- Write-temp-then-rename patterns for atomic, crash-safe file I/O in Rust
- inotify / kqueue based file watching integrated cleanly with a Ratatui event loop
- Fuzzy ranking algorithms: start-of-label beats word-boundary beats mid-word
- Designing a dual TUI + CLI interface from a single binary without duplicating logic
- Balancing feature richness with the todo.txt philosophy of plain-text interoperability
Kairos: Keyboard-First todo.txt in the Terminal
Overview
Kairos is a terminal application built around the todo.txt open standard. It gives the format a fast, Vim-driven interface without breaking compatibility with any other tool that reads the same plain-text file.
The design follows one rule: every change kairos makes is a valid todo.txt line you can open in any editor, sync with any tool, or process with any script.
Core Features
Vim Keys, No Surprises
j / k to move, dd to delete, gg / G to jump, u to undo across 50 levels. Chord sequences (gg, dd, fp, fc) open a visible 600 ms window so key combos never fire unexpectedly.
TUI and CLI in One Binary
Run kairos for the interactive UI. Run kairos <command> for a todo.txt-cli-compatible command line — add, ls, do, pri, archive — with --json output and full $TODO_DIR / $TODO_FILE / $DONE_FILE support. Same binary, same logic.
Natural-Language Add
Type prose into the add prompt: Pay rent monthly on the first, show 3 days before due, project home. Kairos rewrites it to canonical todo.txt for review before saving. Fully local, fully offline — no API call, no service, no dependency.
Phone Capture
Press s to generate a QR code pointing at a tiny PWA served on your machine's LAN. Type tasks from your phone and they land in a sibling inbox.txt first — a deliberate staging area so any source that can append a line (iOS Shortcuts, cron, shell script) is a valid capture source.
Atomic, Sync-Friendly Writes
Every save goes through write-temp-then-rename. If Dropbox, an editor, or a script modifies the file while kairos is open, kairos detects the change on the next keypress — or within ~250 ms while idle — and reloads with a visible notice.
Command Palette
: or Ctrl-P opens a fuzzy palette over every action. The same matcher powers / search: start-of-label hits rank above word-boundary hits, which rank above mid-word hits.
Filter, Sort, Multi-Select
Cycle by +project or @context, sort by priority / due date / file order. Visual mode enables bulk-complete or bulk-delete across any selection.
Saved Searches
Name the active /-search with fs, recall it by cycling saved filters with ff. Stored as plain filter.<name> lines in the config — hand-editable, no binary state.
Five Themes, Three Densities
Cycle themes with T and density with D. Choices persist across sessions. The Terminal theme respects your terminal emulator's own palette, including opacity and blur. Custom themes load from ~/.config/kairos/themes/*.toml.
Technical Highlights
- Language: Rust (2024 edition)
- UI Layer: Ratatui for the terminal interface
- File I/O: write-temp-then-rename for atomic, crash-safe updates
- Change Detection: filesystem events integrated into the Ratatui event loop
- Distribution: single static binary — curl installer, Homebrew tap, PowerShell installer for Windows
Why This Project Matters
todo.txt has existed for over a decade because plain text never rots. Kairos is a bet that the format deserves a first-class interactive experience without giving up the properties that made it last: portability, simplicity, and full ownership.
The project also serves as a practical exploration of writing production-quality TUI software in Rust — where correctness guarantees from the type system map directly onto reliability guarantees for the user.