https://github.com/cxrlos/ratatoist
Keyboard-driven terminal UI for Todoist. Vim motions, async Rust, threaded comments, priority management all without leaving your terminal
https://github.com/cxrlos/ratatoist
cli gtd nvim nvim-plugin productivity ratatui rust rust-crate terminal todo-app todoist todoist-api todoist-tasks todolist vim
Last synced: 4 months ago
JSON representation
Keyboard-driven terminal UI for Todoist. Vim motions, async Rust, threaded comments, priority management all without leaving your terminal
- Host: GitHub
- URL: https://github.com/cxrlos/ratatoist
- Owner: cxrlos
- License: mit
- Created: 2026-02-20T18:46:33.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-25T05:21:48.000Z (4 months ago)
- Last Synced: 2026-02-25T09:57:37.716Z (4 months ago)
- Topics: cli, gtd, nvim, nvim-plugin, productivity, ratatui, rust, rust-crate, terminal, todo-app, todoist, todoist-api, todoist-tasks, todolist, vim
- Language: Rust
- Homepage:
- Size: 193 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
░█▀▄░█▀█░▀█▀░█▀█░▀█▀░█▀█░▀█▀░█▀▀░▀█▀
░█▀▄░█▀█░░█░░█▀█░░█░░█░█░░█░░▀▀█░░█░
░▀░▀░▀░▀░░▀░░▀░▀░░▀░░▀▀▀░▀▀▀░▀▀▀░░▀░
Your Todoist inbox, without leaving the terminal.
---
- **Fast** — incremental delta sync, real-time WebSocket updates, exponential-backoff retries
- **Vim-native** — `j`/`k`/`h`/`l`, folds, modal editing; standard arrow-key mode also available
- **Polished** — threaded comments, priority indicators, human-readable dates, 10 built-in themes
- **Secure** — token never logged, config file permissions validated
## Packages
| Crate | Description |
| ------------------------------------------ | -------------------------------------------- |
| [`ratatoist-core`](crates/ratatoist-core/) | Todoist Sync API client, config, logging |
| [`ratatoist-tui`](crates/ratatoist-tui/) | Terminal UI binary (installs as `ratatoist`) |
| [`ratatoist-nvim`](crates/ratatoist-nvim/) | Neovim plugin — coming soon |
## Quick start
```sh
git clone https://github.com/cxrlos/ratatoist.git
cd ratatoist
cargo install --path crates/ratatoist-tui
```
Run the guided setup (validates your token and optionally writes a shell alias):
```sh
ratatoist --new-user
```
Or configure manually (token from [Todoist settings](https://app.todoist.com/app/settings/integrations)):
```sh
mkdir -p ~/.config/ratatoist
echo 'api_token = "your-token"' > ~/.config/ratatoist/config.toml
chmod 600 ~/.config/ratatoist/config.toml
ratatoist
```
## Features
Navigation and views
- Dual input modes: Vim (Normal/Visual/Insert) and Standard (arrows/Enter)
- Project tree with workspaces, folders, and favorites pinned to top
- Folder expand/collapse (`Space` in Projects pane)
- Task hierarchy with foldable subtask trees (`Space`, `za`/`zR`/`zM`)
- Task detail pane with scrollable content, comments, and metadata
- StatsDock: overdue / today / week / P1–P4 counts; click to filter tasks (`f`)
- Active / Done / Both task filter cycling (`f`)
- Sort cycling: default / priority / due date / created (`o`)
- Splash screen with ASCII art and terminal-adaptive progress bar
Task operations
- Complete / uncomplete (`x`) with optimistic UI — instant feedback, reverts on error
- Quick-add (`a`) with multi-field form: content, priority, due date, project
- Inline field editing in detail pane (`i` / `Enter`)
- Priority picker popup with visual selector
- Star / unstar projects (`s`)
- View completed tasks per project (Done / Both filter fetches from API)
Comments and collaboration
- Multi-user comment threads with per-user colors
- Consecutive same-user message collapsing
- Attachment display with file type metadata
- Add comments from the detail pane (`c`)
- Collaborator name resolution from API
Theming
- 10 built-in themes: Rose Pine, Gruvbox Dark, Dracula, Nord, One Dark, Solarized Dark, Catppuccin Mocha, Tokyo Night, Monokai, Material Dark
- Theme picker in Settings (`,` → theme)
- Custom themes: drop any Base16 JSON file into `~/.config/ratatoist/themes/`
- Theme and idle timeout preferences persisted across sessions
Developer experience
- Structured JSON logging (`--debug`)
- Error popups with context and suggestions
- Dimmed background overlay on popups
- Keybinding cheatsheet (`?`)
- `--new-user` onboarding: token entry + shell alias setup
- `--idle-forcer` flag for testing idle timeout (adds 5 s option)
## Requirements
- Rust 1.85+ (edition 2024)
- A [Todoist](https://todoist.com) account with API token
- A true-color terminal (Alacritty, iTerm2, WezTerm, Kitty, etc.)
## Documentation
| | |
| ----------------------------------------------------------- | -------------------------------------------------- |
| [TUI keybindings and usage](crates/ratatoist-tui/README.md) | Full key reference for both Vim and Standard modes |
| [Core library API](crates/ratatoist-core/README.md) | Using the Todoist client in your own Rust projects |
| [Changelog](CHANGELOG.md) | Version history |
## Development
```sh
cargo run -p ratatoist-tui # run TUI
cargo run -p ratatoist-tui -- --debug # with debug logs
cargo build --workspace --release # build all
./scripts/format.sh # format code
cargo clippy --workspace # lint
cargo test --workspace # test
```
## Roadmap
- [ ] Delete task with confirmation
- [ ] Global search (`/`) with ranked results
- [ ] Move task between projects
- [ ] Undo / redo stack
- [ ] Calendar and Board views
- [ ] Neovim plugin
## License
MIT