Local-first terminal todo sessions with a full-screen TUI, immutable revisions, and SQLite persistence.
When work spans shell scripts, scratch markdown, and half-finished terminal notes, preserving a clean session history gets noisy fast. todui gives you one local place to capture todo sessions, browse immutable revisions, keep notes close to the work, and stay in the terminal from quick CLI automation to full-screen planning.
npx -y @roberttlange/todui --helpnpm install -g @roberttlange/todui
toduiThe npm package downloads a prebuilt binary for macOS/Linux on x64 and arm64; a local Rust toolchain is not required for the npm install path.
cargo install --path .
todui --helpRunning todui without a subcommand opens the overview screen. If you mostly work from scripts or agent loops, you can stay in CLI mode with session, add, done, repo, and export.
# Create a new session for the work you want to track.
todui session new "Writing Sprint" --tag work
# Add a concrete drafting task with an attached note.
todui add "Draft design spec" --session writing-sprint --note "cover CLI and TUI"
# Attach a todo to a GitHub repo so it can be queried later.
todui add "Review keybindings" --session writing-sprint --repo @exampleorg/todui-keymove
# Record a human-authored item instead of the default agent provenance.
todui add "Interview notes" --session writing-sprint --human
# Jump straight into the live session in the TUI.
todui resume writing-sprint
# Open the immutable revision history for that session.
todui session history writing-sprint
# Export the current session, including notes, as markdown.
todui export md writing-sprint --include-notesCLI todo mutations default to agent provenance. Pass --human on add or done when the action should be recorded as human-authored.
- Session-based todo lists with one canonical session name per workspace, so project work stays grouped instead of getting scattered across ad hoc scratch files.
- A full-screen TUI and a scriptable CLI backed by the same local SQLite database, which makes it practical to mix interactive planning with shell automation.
- Immutable revision history for sessions, including read-only resume and export flows for older states when you need to audit what changed.
- Human versus agent provenance on todo creation and completion, which is useful when multiple tools or collaborators are touching the same session.
- Overview notes, per-todo notes, repo metadata, and markdown export so the session can double as a lightweight working log.
- A built-in Pomodoro timer surfaced in both overview and live session screens rather than living in a separate app.
todui looks for a config file and database path independently. The config file location decides which TOML file gets loaded; the database path is then resolved from CLI or env overrides first, then from the loaded config file.
| Setting | Default | Override order | Notes |
|---|---|---|---|
| Config file path | ~/.todui/config.toml |
todui --config /absolute/path/to/config.toml -> TODO_TUI_CONFIG -> default path |
If the file does not exist, todui falls back to built-in defaults. |
| Database path | ~/.local/share/todui/todui.db |
TODO_TUI_DB -> [database].path in the selected config file -> default path |
Use an absolute path in config if you want the DB somewhere else. |
The example config exposes four areas:
| Section | Purpose | Example keys |
|---|---|---|
[database] |
Point todui at a specific SQLite file. |
path |
[theme] |
Pick the overall color mode and accent. | mode, accent |
[pomodoro] |
Tune timer lengths and completion notifications. | focus_minutes, short_break_minutes, long_break_minutes, notify_on_complete |
[keys] |
Override default key bindings for core navigation and actions. | up, down, toggle_done, history, pomodoro |
From a source checkout or unpacked npm tarball, seed a config file from the example:
mkdir -p ~/.todui
cp config.example.toml ~/.todui/config.tomlMinimal example:
[theme]
mode = "dark"
accent = "cyan"If you only want a quick visual change, setting [theme] is enough. If you are integrating todui into a larger local workflow, the most common next step is pinning [database].path so scripts and the TUI both point at an explicit database location.
j/k, arrows: move selectionn: create a session or todoe: edit the selected session or todof: cycle provenance filter (all,human,agent)space/x: toggle completionH: open session historyr: return from a revision to the live headm: edit overview notesq/Esc: close overlay or quit
This repo ships two workflow skills for long-running agent work. They are meant for Codex or Claude-style coding agents that need a repeatable planning/execution loop and a shared todui session as their ledger.
npx skills add RobertTLange/todui --skill '*' -a claude-code -a codex -yThat command installs both bundled skills from this repository for supported agents.
See skills/project-plan/SKILL.md.
Use this when you have a spec and want an agent to turn it into an execution pack under docs/. The skill reads a source spec, creates or reuses a deterministic todui session for the repo, writes docs/prompt.md, docs/plan.md, docs/implement.md, and docs/documentation.md, and keeps fixed planning todos in sync while it does so.
In practice, project-plan is the right starting point when the work is still ambiguous and you want the agent to freeze scope, milestones, assumptions, and validation steps before touching code.
See skills/project-build/SKILL.md.
Use this after a plan pack already exists under docs/. The skill treats the planning pack as the source of truth, creates or reuses one repo session in todui, mirrors milestones into todos, executes them one at a time, records blockers, and leaves the current repo state resumable for another agent.
In practice, project-build is the execution companion to project-plan: first generate the pack, then ship against it without losing milestone state in a long chat thread.
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
TODOUI_SKIP_DOWNLOAD=1 npm ci
npm run build
npm test