A beautiful terminal UI for managing tasks in Markdown files with vim-like navigation
npm install todo-tuiA beautiful and intuitive terminal application (TUI) for managing tasks in Markdown files.
!Node.js
!TypeScript
Manage your tasks directly from your terminal with a beautiful, keyboard-driven interface. Perfect for developers who live in the terminal and want to keep their workflow uninterrupted. Your tasks are stored in a simple Markdown file that you can edit manually or with the app.
Born from necessity: This app was created by someone with ADHD who needed a simple, highly visual way to manage daily tasks. The interface is intentionally designed to reduce cognitive load and maintain focus, with features like the 3-task limit in the "DOING" section to prevent overwhelm.
Key Benefits:
- 🚀 Lightning-fast keyboard navigation (vim-like)
- 📝 Human-readable Markdown storage
- 🔄 Live sync with external file changes
- 🎨 Beautiful, distraction-free interface
- 💪 Powerful batch operations
- 🧠 ADHD-friendly design (max 3 tasks in "DOING" to prevent overwhelm)
- 🎯 "Today's focus" field to set daily priorities
- ✨ Clear visual hierarchy and color-coded sections
_Coming soon.
- Features
- Installation
- Usage
- Shortcuts
- Markdown File Structure
- Development
- Detailed Features
- Technologies
- Contributing
- License
- 🎨 Colorful and organized terminal interface
- 📝 Uses Markdown file as database (manually editable)
- 🔄 Automatically syncs with external file changes
- ⌨️ Keyboard navigation (vim-like: h/j/k/l)
- 🏷️ Support for tags, deadlines, and time estimates
- 🚀 Priority markers (⚡ important, 🚀 quick)
- 📦 Multiple task selection for batch operations
- 🔝 Task reordering with Ctrl+arrows or K/J
- 🎯 Editable "Today's Focus" field
- 🔥 Limit of 3 tasks in "DOING" section
- 📱 Responsive interface that adapts to terminal size
- 💾 Automatic save on all operations
No installation needed! Just run:
``bashUse default file (~/.config/todo-tui/TODO.md)
npx todo-tui
$3
bash
With npm
npm install -g todo-tuiWith pnpm
pnpm add -g todo-tui
`$3
bash
Navigate to directory
cd todo-tuiInstall dependencies
pnpm installRun in development mode
pnpm dev
`📖 Usage
bash
Use default file (~/.config/todo-tui/TODO.md)
todoSpecify custom file
todo ~/my-todo.md
`Default file:
On first run, the app automatically creates:
- The
directory
- The TODO.md file with an initial template⌨️ Shortcuts
$3
| Key | Action |
|-----|--------|
|
↑ / k | Previous task |
| ↓ / j | Next task |
| ← / h | Previous section |
| → / l / Tab | Next section |$3
| Key | Action |
|-----|--------|
|
Enter | Toggle selected task(s) |
| a | Add new task |
| e | Edit current task |
| d (2x) | Delete task(s) (press twice) |
| m | Move task to another section |
| f | Edit today's focus |$3
| Key | Action |
|-----|--------|
|
Space | Select/Deselect current task |
| s | Select/Deselect all tasks in section |
| S | Select/Deselect all tasks |Tip: Select multiple tasks and use
Enter, d, m or numbers for batch actions!$3
| Key | Action |
|-----|--------|
|
K / Ctrl+↑ | Move task(s) up |
| J / Ctrl+↓ | Move task(s) down |Note: Moving at the beginning/end of a section moves to the previous/next section.
$3
| Key | Move to |
|-----|---------|
|
1 | 🔥 DOING |
| 2 | 📌 NEXT |
| 3 | ⏳ WAITING |
| 4 | 🚧 BLOCKED |
| 5 | 💡 IDEAS |
| 0 | ✅ DONE |$3
| Key | Action |
|-----|--------|
|
r | Reload file |
| ? | Show full help |
| q | Quit |
| Esc | Cancel/Go back |📁 Markdown File Structure
The app expects a Markdown file with specific sections:
`markdown
📋 TASKS
> Today's focus: _Your priorities for the day_
🔥 DOING (max. 3)
- [ ] Task in progress #tag ~30min ⚡📌 NEXT
- [ ] Next task #work 📅 20/12
- [ ] Quick task 🚀⏳ WAITING
- [ ] Waiting for approval → _John/code review_🚧 BLOCKED
- [ ] Blocked task → _External dependency_💡 IDEAS / SOMEDAY
- Future idea
- [ ] Another idea with checkbox✅ DONE
- [x] ~~Completed task~~ ✓ 15/12
$3
- Tags:
(can be multiple)
- Deadline: 📅 DD/MM (due date)
- Duration: ~30min, ~2h (estimated time)
- Markers:
- ⚡ = High priority/important
- 🚀 = Quick task
- Waiting/Blocked: → _reason or person_
- Completion: (automatically added when marked as done)🛠️ Development
`bash
Install dependencies
pnpm installRun in dev mode (with hot reload)
pnpm devBuild for production
pnpm buildRun build
pnpm start
`🎨 Detailed Features
$3
Interactive wizard that prompts for:
1. Task text
2. Tags (separated by comma or space)
3. Deadline (format DD/MM)
4. Estimated duration (e.g., 30min, 2h)
5. Priority marker (None, ⚡ Important, 🚀 Quick)$3
Allows editing all fields of an existing task using the same wizard.$3
- Manual: Key opens section selection menu
- Quick: Keys 1-5 and 0 move directly
- Reorder: K/J or Ctrl+↑/Ctrl+↓ to reorganize within or between sections$3
1. Use Space to select individual tasks
2. Use s to select/deselect entire section
3. Use S to select/deselect all tasks
4. Selected tasks are marked with visual indicator
5. Actions apply to all selected tasks$3
When pressing Enter on a task (or multiple selected tasks):
- Task is automatically moved to "DONE"
- Text gets strikethrough (~~text~~)
- Completion date is automatically added
- Can be reopened by pressing Enter again in the done section$3
- The app monitors the file with chokidar
- External changes are detected and automatically reloaded
- Visual notification when file is updated
- You can manually edit the file and changes appear in the interface📦 Technologies
- Node.js - Runtime
- TypeScript - Language
- Ink - React for terminal
- Rollup - Bundler
- Chokidar - File watcher
❓ FAQ
$3
By default, tasks are stored in
. You can specify a custom file path when running the app.$3
Yes! The file is just a Markdown file. You can edit it with any text editor, and the app will automatically detect and reload changes.
$3
The app monitors the file for changes. If you edit it externally, the app will reload automatically. However, if you're running multiple instances of the app, the last save will win.
$3
Yes! The app is built with Node.js and works on all platforms.
$3
Simply copy the
TODO.md file. You can also use git to version control your tasks file.$3
Yes! Store your
TODO.md in a synced folder (Dropbox, Google Drive, Git repository, etc.) and point the app to that file.🤝 Contributing
Contributions are welcome! Here's how you can help:
1. Fork the repository
2. Create a feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull RequestPlease read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.
$3
`bash
git clone https://github.com/felipechierice/todo-tui.git
cd todo-tui
pnpm install
pnpm dev
``Found a bug? Please open an issue with:
- A clear description of the problem
- Steps to reproduce
- Expected vs actual behavior
- Your environment (OS, Node version)
Have an idea? Open an issue and describe:
- The problem you're trying to solve
- Your proposed solution
- Any alternatives you've considered
MIT © Felipe Chierice (felipe.chierice@hotmail.com)
---