tasktui

A tmux-first TUI for managing project tasks as plain Markdown files.

No databases, no cloud sync, no accounts. Tasks live as .md files in your repo, tracked by git alongside your code.

Quick Start

# Install (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/carlMobileDev/tasktui/main/install.sh | bash
# Or build from source
cargo build --release
# Initialize in any project directorycd your-project
tasktui init
# Create some tasks
tasktui add "Set up CI pipeline" --priority p0 --tags "infra,ci"
tasktui add "Write user auth" --priority p1
tasktui add "Update docs" --tags "docs"# Launch the TUI
tasktui

How It Works

tasktui init creates a .tasktui/ directory in your project:

.tasktui/
config.toml # statuses, priorities, branch patterns, editor
tasks/ # one Markdown file per task

Each task is a Markdown file with YAML frontmatter:

---id: 1title: Set up CI pipelinestatus: inboxpriority: p0tags:
- infra
- cibranch: task/1-set-up-ci-pipelinecreated: 2025-01-15T10:30:00Zmodified: 2025-01-15T10:30:00Zdue: '2025-02-01'related_files:
- .github/workflows/ci.yml---## Description
Configure GitHub Actions for the project.
## Acceptance Criteria- Runs tests on every PR
- Builds release artifacts on merge to main
## Notes

Edit tasks with any text editor. The TUI reads them on the fly.

CLI Commands

Command	Description
tasktui init	Initialize .tasktui/ in the current directory
tasktui add "title"	Create a new task
tasktui list	List tasks (table format)
tasktui list --format json	List tasks as JSON
tasktui show <id>	Print task details
tasktui edit <id>	Open task in $EDITOR
tasktui copy <id>	Copy task context to clipboard (for AI agents)
tasktui delete <id>	Permanently delete a task

Filters for list

tasktui list --status todo
tasktui list --priority p0,p1
tasktui list --tag backend

Options for add

tasktui add "My task" --priority p0 --status inbox --tags "backend,api" --body "Some description"

TUI Views

The TUI has four views, switched with number keys 1-4. The workflow follows a focus list model: triage tasks in Plan, order them in Pick, work on them in Focus, review completed work in Review.

1. Focus

Your active workspace. Shows the tasks you're currently working on (up to 3 active tasks). A single active task displays its full body, metadata, and related files. Multiple active tasks show the primary task with an "also active" bar for the others. Navigate between active tasks with j/k.

2. Pick

The ready queue. Tasks with status "ready" appear here, ordered by ready_order. Select a task and press Enter to start working on it (moves to active, switches to Focus). Reorder the queue with J/K.

3. Plan

The inbox for triage. New tasks land here with status "inbox", sorted by priority then creation date. Use Space to select tasks, then Enter to promote them to the ready queue. Archive tasks you don't need with d.

4. Review

Completed work grouped by week. Browse what you've shipped, sorted by completion date. Read-only.

Keybindings

Press ? in any view to see the full help popup.

Global

Key	Action
1-4	Switch view
c	Create task
/	Fuzzy search
f	Filter panel
?	Help
q / Q	Quit

Focus View

Key	Action
j / k	Cycle active tasks or scroll body
d	Mark task done
s	Shelve back to inbox
Tab	Jump to Pick view
e	Edit in $EDITOR
y	Copy to clipboard (agent format)
Enter	Open task detail
r	Reload from disk

Pick View

Key	Action
j / k	Navigate queue
Enter	Start task (move to active, switch to Focus)
J / K	Reorder in ready queue
s	Shelve back to inbox
e	Edit in $EDITOR
y	Copy to clipboard
r	Reload from disk

Plan View

Key	Action
j / k	Navigate inbox
Space	Toggle selection
Enter	Promote selected to ready queue
a	Select all
x	Clear selection
d	Archive task
e	Edit in $EDITOR
r	Reload from disk

Review View

Key	Action
j / k	Scroll
r	Reload from disk

Task Detail Popup

Key	Action
j / k	Scroll
s	Cycle status
p	Cycle priority
e	Edit in $EDITOR
y	Copy to clipboard
d	Archive task
D	Delete task permanently
Esc	Close

Filter Panel

Key	Action
1	Cycle status filter
2	Cycle priority filter
3	Cycle tag filter
x	Clear all filters
Esc / f	Close

Agent Copy

Press y on any task to copy a rich context block to the clipboard, designed for pasting into AI coding assistants. It includes:

• Task metadata (status, priority, branch, due date, tags)
• Contents of related files (capped at 200 lines each)
• Full task body

The clipboard uses pbcopy (macOS), xclip/xsel (Linux), or OSC 52 escape sequences as a fallback for remote tmux sessions.

Configuration

Edit .tasktui/config.toml to customize:

[general]
default_view = "focus"# focus, pick, plan, revieweditor = "$EDITOR"# or "vim", "nvim", "code", etc.
[statuses]
order = ["inbox", "ready", "active", "done", "archived"]
default = "inbox"
[priorities]
order = ["p0", "p1", "p2", "p3"]
default = "p2"
[branch]
pattern = "task/{id}-{slug}"
[agent_copy]
include_related_files = true

Due Dates

Tasks with a due field show visual indicators:

• Red "OVERDUE" when past due
• Yellow "soon" when due within 3 days
• Normal otherwise

Set due dates by editing the task file directly (the due field in frontmatter, format: YYYY-MM-DD).

Building

Requires Rust 1.70+.

cargo build --release
# Binary at target/release/tasktui# Run tests
cargo test

Design Decisions

• One file per task: No database, no index. Tasks are human-readable Markdown files that git tracks naturally.
• YAML frontmatter: Structured metadata alongside freeform Markdown body. Same format used by Jekyll, Hugo, Obsidian.
• Focus list workflow: Tasks flow through inbox → ready → active → done. Triage in Plan, prioritize in Pick, execute in Focus.
• No sync: Your repo is the source of truth. Use git for history, branching, and collaboration.
• Tmux-first: If you're not in tmux, tasktui will try to launch a tmux session automatically. Works fine without tmux too.
• Scales to ~200 tasks: File reads are fast enough. If you need 1000+ tasks, you'd want an index file.