Tuido 📝

A TUI (Terminal User Interface) Kanban board for TODO.md files.

中文 README

Features

• 📋 Parse TODO.md files with simple list syntax
• 📊 Dynamic columns based on markdown sections (## Heading)
• 🎨 Multiple themes (Dracula, Nord, Monokai, Solarized, etc.)
• ⌨️ Vim-style keybindings (h/j/k/l)
• ↔️ Move tasks between columns with Shift+Arrow keys
• 🏷️ Support for tags (#tag), priority (!P0/!P1/!P2/!P3/!P4), timestamp (~YYYY-MM-DDTHH:MM)
• 💾 Save changes back to TODO.md
• 🌏 Global view - View all projects' tasks from Feishu table
• 🔄 Bi-directional sync - Push to and pull from Feishu table

Installation

# Clone or download the repository
cd tuido

# Install in editable mode
pip install -e .

Usage

# Open TUI Kanban board for TODO.md in current directory (default)
tuido tui

# Create a sample TODO.md file
tuido create

# List tasks (optionally filtered)
tuido list
tuido list --status "Active"
tuido list --tag feature
tuido list --priority P1

# Add a new task
tuido add 'Fix bug #bug !P0'

# Push tasks to Feishu table
tuido push

# Pull tasks from Feishu table
tuido pull

# Use global options (--path and --remote)
tuido --path /path/to/project tui
tuido --path /path/to/project list --status Active
tuido --remote tui           # Open remote global view
tuido --remote list          # List tasks from remote
tuido --remote add 'Task'    # Add task to remote
tuido --path /path/to/project --remote push

Global Options:

• --path PATH - Path to TODO.md or directory (default: current directory)
• --remote - Use remote Feishu table (only for tui, list, push, add commands)

Note: --path and --remote are global options that must be placed before the command.

Keyboard Shortcuts

Navigation (Vim-style)

• ↑ / k - Previous task
• ↓ / j - Next task
• ← / h - Previous column
• → / l - Next column

Move Tasks (Between Columns)

• Shift+↑ / Shift+K - Move task up (reorder within column)
• Shift+↓ / Shift+J - Move task down (reorder within column)
• Shift+← / Shift+H - Move task to left column
• Shift+→ / Shift+L - Move task to right column

Actions

• a - Add new task
• d - Delete task
• e - Edit task
• r - Refresh from file
• s - Save to file
• t - Switch theme
• q / Ctrl+C - Quit
• ? - Show help

TODO.md Format

---
theme: dracula
---

# TODO

## Todo
- Task to do #feature !P1 ~2026-02-28T10:30
- Another task #bug ~2026-02-28T09:00

## Active
- Currently working on ~2026-02-28T14:00

## Done
- Completed task ~2026-02-27T16:30

Dynamic Columns

Columns are automatically created from ## headings in your TODO.md file. You can define any columns you need:

• ## Todo - Tasks to do
• ## Active - Tasks being worked on
• ## Done - Completed tasks

The column order follows the order they appear in the file.

Task Syntax

• - - Task prefix (required)
• #tag - Tags (e.g., #feature, #bug, #docs)
• !P0 / !P1 / !P2 / !P3 / !P4 - Priority (P0 = highest, P4 = lowest)
• ~YYYY-MM-DDTHH:MM - Last updated timestamp (e.g., ~2026-02-28T14:30)

Task status is determined by which section (## Todo, ## Active, etc.) it belongs to.

Inline Styling

Task titles support Markdown-style inline formatting in the TUI:

• **bold** or __bold__ - Bold text
• `code` - Code text (cyan color)
• ~~strikethrough~~ - Strikethrough text

Examples:

- Implement **bold** and `code` support !P1 #ui
- ~~Deprecated feature~~ will be removed in v2.0
- **Important:** Check `config.yaml` before running

Note: The timestamp is automatically updated when you move or reorder tasks in the TUI, and is synced with Feishu's Timestamp field.

Configuration

Front Matter (TODO.md)

Add configuration at the beginning of your TODO.md:

---
theme: nord
remote:
  feishu_api_endpoint: https://open.feishu.cn/open-apis
  feishu_table_app_token: your_app_token
  feishu_table_id: your_table_id
  feishu_table_view_id: your_view_id
---

Global Config (~/.config/tuido/config.yaml)

For Feishu integration, create the config file:

theme: dracula
remote:
  feishu_api_endpoint: https://open.feishu.cn/open-apis
  feishu_table_app_token: your_table_app_token
  feishu_table_id: your_table_id
  feishu_table_view_id: your_table_view_id
  feishu_bot_app_id: your_bot_app_id
  feishu_bot_app_secret: your_bot_app_secret

Global View

View tasks from all projects in a single interface:

# Show global view from Feishu table
tuido tui --remote

Configuration:

Create ~/.config/tuido/config.yaml with your Feishu credentials (see above).

The global view displays tasks from all projects organized by status columns (Todo, Active, Review, Done).

Feishu Sync

Push to Feishu

Push local tasks to Feishu table:

tuido push

Features:

• Compares local tasks with remote records
• Shows diff preview before pushing
• Creates new tasks, updates modified ones
• Deletes orphaned remote records

Pull from Feishu

Pull remote tasks from Feishu to local:

tuido pull

Features:

• Fetches tasks from Feishu for the current project
• Shows diff preview before applying
• Adds new tasks, updates modified ones
• Removes local tasks deleted remotely
• Automatically saves to TODO.md

Requirements

• Python 3.12+
• textual
• rich
• requests
• pyyaml
• loguru