Skip to content
sjwaskoPublic

About

A fast, local-first terminal client for Vikunja

Topics

Resources

Contributing

Stars

13 stars

Watchers

0 watching

Forks

Repository files navigation

tui-do

Sponsor Buy me a coffee

A fast, local-first terminal client for Vikunja.

tui-do keeps your tasks in a local SQLite store and reconciles with the server in the background. It starts instantly, works with the server unreachable, and never blocks a frame on a network call. Built to be the foundation for tracking not only your tasks, but also agentic tasks and workflows.

Feel the flow break when you have to tab out of tmux or herdr or your terminal sessions to go to a PWA or the web page for your Vikunja instance? I'm with you, tui-do is the answer!

Your agents can file tasks too. tui-do add 'Chase the upstream ticket *urgent !4 +Infra tomorrow' turns one line into a task, with its project, label, priority and due date, and queues it through the same offline-safe outbox the interface uses. Give your agent skills/tui-do/SKILL.md and it knows how; see For agents.

Status: 1.2. v1.2.2 is published and is what the commands below install. Everything documented here works and is used daily against a real Vikunja; what's planned is set out rather than left to be discovered.

tui-do: an agent files a task from the shell while the interface is open beside it, and picks it up on the next sync

The right-hand pane is a scripted stand-in for an agent, not a live model, but the tui-do add it runs is real, and the task it files is the one the interface pulls in. Regenerate it with docs/demo/tui-do-agent.tape.

Warning

Back up your Vikunja data before you use this. tui-do writes to your real server: it creates, edits, completes and deletes tasks, and every sync reconciles your local copy against what the server holds.

Undo (U) covers most of what you do from the interface, and is worth knowing the limits of. Undoing a delete re-creates the task with a new id, so its comments and attachments do not come back, because Vikunja has no undelete. Creating a label cannot be undone at all. And on a genuine conflict, where you and another client have changed the same field, your value wins and overwrites theirs by design.

Take an export first (Vikunja can export your account's data from your user settings) and keep it until you trust this. The software comes with no warranty of any kind, and the authors accept no liability for lost or damaged data. The formal terms are in License; this paragraph is the plain-English version.

The local store (~/.local/share/tui-do/tui-do.db on Linux; see Where tui-do keeps its files for macOS) is disposable: delete it and the next run re-syncs. What is worth protecting is what lives on your Vikunja server. Open issues are listed in bugs.md.

What it does

  • Reads instantly and works offline. Every read is answered by the local store, so the interface does not wait on the network, and neither startup nor editing needs the server to be reachable. Queue up your todos while on the plane or train with no wifi.
  • Writes optimistically. A change lands locally and is queued; the sync engine sends it when it can. A rejection rolls the change back and says so. A failure blocks that one task, not the queue.
  • Quick-add syntax for creating tasks in one line, from the interface or the shell.
  • A command line agents can use. tui-do add files a task from one line, --tokens lists the names a line may use, and --dry-run checks a generated line before anything is queued. See For agents.
  • Task descriptions rendered: Markdown, plain text, or the HTML Vikunja's web editor stores, in your own colours, in process, with no external tools.
  • Labels, priorities, due dates, projects, with fuzzy pickers for each. Labels can be created, renamed and recoloured from inside tui-do.
  • Undo and redo, riding on the same optimistic-write mechanism rather than a parallel one.
  • Configurable column layouts and quick actions.

Install

One binary, needing no Rust, no C toolchain and no system SQLite. Building from source is only needed to modify tui-do.

On Linux it is statically linked — nothing but a kernel is required, and the same file runs on Arch, Ubuntu, Debian, Fedora and older LTS releases alike. On macOS it is not, and cannot be: Apple ships no static libSystem, so the Mac binary links the system libraries every Mac already has. The release refuses to publish one that reaches outside /usr/lib and /System/Library, which is the same guarantee arrived at differently.

Tested on: Ubuntu 24.04, Ubuntu 26.04, Omarchy 4.0.1-1j, Raspberry Pi OS (64-bit, Raspberry Pi 5), Ubuntu 24.04 (Raspberry Pi 4 Model B). Your results may vary on other releases and distributions.

tag=v1.2.2
arch=$(uname -m)          # x86_64 or aarch64
base=https://github.com/sjwasko/tui-do/releases/download/$tag

curl -fLO "$base/tui-do-$tag-$arch-unknown-linux-musl.tar.gz"
curl -fLO "$base/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS

tar -xzf "tui-do-$tag-$arch-unknown-linux-musl.tar.gz"
install -Dm755 "tui-do-$tag-$arch-unknown-linux-musl/tui-do" ~/.local/bin/tui-do

The sha256sum --check line is worth keeping: it catches a truncated download, which otherwise shows up as a confusing crash rather than as the incomplete file it is. The only external program tui-do ever calls is the one that opens a link when you press o: xdg-open on Linux, open on macOS.

macOS

brew install sjwasko/tui-do/tui-do

The release also carries tui-do-<tag>-aarch64-apple-darwin.tar.gz if you would rather not use Homebrew. Two things differ from the Linux recipe above and both fail confusingly: macOS has no sha256sum (shasum -a 256 --check --ignore-missing instead), and BSD install has no -D (mkdir -p ~/.local/bin first).

Apple Silicon only. There is no Intel build; on an Intel Mac, build from source.

Putting ~/.local/bin on your PATH

Many distributions add it already when the directory exists, so check before changing anything:

command -v tui-do

A path means you are done. Nothing means your shell cannot find it yet, so add it and then open a new terminal:

# bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# fish -- persistent, and takes effect immediately
fish_add_path ~/.local/bin

fish_add_path needs fish 3.2 or newer, and is preferred over a set -x PATH line in config.fish because it records the directory once, so re-running it does not stack duplicates. On older fish, add set -gx PATH $HOME/.local/bin $PATH to config.fish instead.

If you use bash and it still is not found in a login shell (over SSH, say), your system reads ~/.profile rather than ~/.bashrc for those; add the same export line there too.

REQUIRED - First time setup

Run:

tui-do login

It asks for your server, points you at Vikunja's API-token page, takes the token without echoing it, and writes both files for you — the config, and the token at mode 0600. It is the same command on Linux and macOS; only where the files land differs.

It checks the token before it writes anything. Vikunja's tokens are scoped, the scopes are not obvious, and a token missing other → user fails in a way that reads like the token is wrong rather than incomplete — see Token permissions. login asks the server who you are and either prints "Signed in as …" or tells you what is missing, while you are still looking at the checkboxes.

Run it again whenever you rotate a token or move servers. An existing config is read and updated, never replaced, so anything you have tuned survives.

To script it, pass the server and pipe the token in:

tui-do login --url vikunja.example.com < token
Writing the two files by hand instead

Nothing about login is privileged — it writes ordinary files you can write yourself.

On Linux:

mkdir -p ~/.config/tui-do
printf '%s' 'YOUR_TOKEN_HERE' > ~/.config/tui-do/token
chmod 600 ~/.config/tui-do/token
$EDITOR ~/.config/tui-do/config.yaml

Or on macOS, where all three files share one directory. Note the space in the path, which is why every line here is quoted:

dir="$HOME/Library/Application Support/tui-do"
mkdir -p "$dir"
printf '%s' 'YOUR_TOKEN_HERE' > "$dir/token"
chmod 600 "$dir/token"
$EDITOR "$dir/config.yaml"

Create the API token in Vikunja under Settings → API tokens first.

A URL and somewhere to find the token is the whole minimum, and this file is the same on both platforms — it is also exactly what tui-do login writes:

server:
  url: https://vikunja.example.com
  token_file: token

token_file: token is relative, so it resolves against the directory holding the config that names it. Writing it that way is what makes the config portable: it works unchanged on either platform, and it travels to a new machine alongside its token with no absolute path to keep in step. An absolute path or one starting ~ works too if you would rather be explicit.

Then run tui-do. Everything else has a default; see the configuration reference for the rest.

If tui-do stops with could not read …/config.yaml: No such file or directory, that is a setup that never happened — run tui-do login.

Only the first line of the token file is used, and it is trimmed, so a trailing newline is harmless. TUI_DO_API_TOKEN works instead of the file if you would rather not have one, and TUI_DO_CONFIG overrides where the config is read from. tui-do warns if either file is readable by other accounts.

Where tui-do keeps its files

tui-do follows each platform's own convention rather than imposing one, so the paths differ. Deleting the database is safe on either: the next run re-syncs.

Linux macOS
config ~/.config/tui-do/config.yaml ~/Library/Application Support/tui-do/config.yaml
token ~/.config/tui-do/token ~/Library/Application Support/tui-do/token
store ~/.local/share/tui-do/tui-do.db ~/Library/Application Support/tui-do/tui-do.db

On macOS all three share one directory, where Linux splits config from data. That is what Apple's layout gives, and it is worth knowing before you go looking for a second folder that does not exist.

XDG_CONFIG_HOME and XDG_DATA_HOME are honoured on Linux and deliberately ignored on macOS, which is the platform convention. If you want one path shape across machines of both kinds, set TUI_DO_CONFIG and TUI_DO_DB rather than the XDG variables; --config beats both.

A token_file may be relative, in which case it resolves against the directory holding the config that names it. That is the portable way to write it: the config and its token then travel together to any machine, on either platform, with no absolute path to keep in step.

Configuration reference

tui-do reads the config from the platform path above, or from $XDG_CONFIG_HOME/tui-do/ on Linux. TUI_DO_CONFIG overrides it on both. Only server.url and a credential are required; every other key below shows its default.

server:
  url: https://vikunja.example.com
  # Either point at a file holding the token, or set TUI_DO_API_TOKEN.
  # tui-do warns if the file is readable by other accounts.
  # A relative path resolves against this config's own directory, which is the
  # portable way to write it. Absolute paths and a leading ~ also work.
  token_file: token

sync:
  # The local store answers every read, so this sets staleness rather than speed.
  # Shorter if you have several instances syncing against the same Vikunja.
  # Each sync fetches what changed; once an hour it re-reads everything, which is
  # what notices a task deleted elsewhere. R does that at once.
  interval_seconds: 300
  enabled: true

view:
  default_filter: done = false
  active_layout: default

# Reached with Space, then the key.
quick_actions:
- key: 'u'
  action: priority
  target: 5
- key: 'w'
  action: project
  target: Work

Token permissions

Vikunja's API tokens carry a per-route permission list, and a token that looks complete can still fail. Grant these groups:

group why
other → user Identifies who you are at startup. Without it tui-do does not start.
tasks Read, create, edit, complete and delete tasks
tasks_labels Attach and detach labels, a separate group from labels
labels Create, rename and recolour labels
projects List projects, and move tasks between them
projects_views Read a project's views, which is how the list view is resolved
tasks_assignees Only if you assign people

Two of these are easy to miss and both fail unhelpfully.

other → user is the one that stops tui-do dead. Every task and project call can succeed while GET /user returns 401, and what you see is a red toast reading "not authorized: missing, malformed, expired or otherwise invalid token provided", which reads like the token is wrong when in fact it is merely incomplete.

tasks_labels is not part of labels. With labels alone you can create and rename labels but not put one on a task, so l fails with the same message while everything else works.

Keys

? shows this table inside the application, and : runs any command by name if you would rather not remember a key.

Where Vikunja's web interface has a shortcut, tui-do uses the same key, so t, d, u, g a, p, m, l and e do the same thing in both, and in the omavikunja panel. That changed in 1.2.0: done was d, due date D, add a, undo u, show completed t, and go to a label g l. The first launch after upgrading lists what moved; d on that screen stops it appearing again.

Navigation

j / k, ↓ / ↑ Move down / up
C-d / C-u, PgDn / PgUp Page down / up
g g / G, Home / End Jump to top / bottom
Tab / S-Tab Focus the next / previous pane
g p / g a Go to a project / label
/ Search the current list
Enter Open the selected task
Esc Back to the list, then out of a search

Tasks

n Add a task, in quick-add syntax
e Edit the selected task
t Mark done, or not done
p / d Set priority / due date
l Add or remove labels
m Move to another project
u Open the task's project, keeping the task selected
o Open a link in the selected task
x, Delete Delete the task
U / C-r Undo / redo
Space Configured quick actions

View and application

z s / z p Show or hide the sidebar / preview pane
z d Show or hide completed tasks
L / H Next / previous column layout
r, F5 Sync: push, then fetch what changed
R Sync everything, so deletions made elsewhere are noticed
: / ? Run a command by name / show the keys
q, C-c Quit

o copies rather than opens when there is nothing to open onto. Over SSH the opener would launch a browser on the machine at the far end of the connection instead of the one you are sitting at. So with SSH_CONNECTION set, or -- on Linux -- with neither DISPLAY nor WAYLAND_DISPLAY, o puts the URL on your clipboard over OSC 52, which lands in the terminal you are typing in. That is working as intended, not a missing opener. The toast names what it copied, because a few terminals ship with OSC 52 disabled and tui-do has no way to tell.

The opener is xdg-open on Linux and open on macOS. A local macOS session always has a window server to open onto and sets neither DISPLAY nor WAYLAND_DISPLAY, so only the SSH rule applies there -- over SSH into a Mac, o still copies.

Quick-add syntax

Tokens may appear anywhere in the line. Labels, projects, users, priorities and repeats leave the title wherever they are. A date is always read, but leaves the title only when nothing follows it except whitespace, punctuation and other tokens; anywhere else it stays exactly as typed.

So call mom tomorrow. becomes call mom, and pay rent due friday *bills !3 becomes pay rent, but tomorrow buy milk keeps that title, with any due or start it was typed with, and is still due tomorrow. Two dates at the end (start monday due friday) both come out; a date mid-sentence stays while one at the end still comes out.

+project File it in a project, by title or id: +Legal, +#12
*label Attach a label: *urgent
@user Assign someone: @admin. A name tui-do has not seen on a task stays in the title
!1 … !5 Priority, 1 lowest to 5 highest
a date tomorrow, next friday, 27aug26, aug 27, 2026-08-27, 27/08/2026
due <date> / start <date> The same, said explicitly, and also 27.8, 27/08, 27/08/26
every <n> <unit> Repeat: every 2 weeks, every month. With two everys, the last one that forms a repeat is used

A weekday abbreviation needs due or start too (due fri, start mon): sun, sat and wed are words as well, so water plants in the sun keeps its title. The full name, friday, works anywhere.

A date in digits alone needs due or start in front of it unless it has a four-digit year. call mom due 27.8 is due on 27 August; llvm 1.6 GB, add 1/2 cup and upgrade to 2.6.10 keep their numbers and get no date, because without the keyword those read as a decimal, a fraction or a version as readily as a day. A month name or a four-digit year is never ambiguous and works anywhere — except a dotted date that leads with its year, 2026.1.5, which is a version number's shape and needs the keyword too; write 2026-01-05 instead. tui-do add names any date it set, so a misread one shows up at once: Added "call mom" to Inbox, due Fri 27 Aug 2027.

Check a line before adding it with --dry-run. It parses the line, resolves its project and labels against the local store exactly as a real add would, and prints what it would create and the line in its best form. It queues nothing, writes nothing and contacts no server, and it fails, with the same message, wherever a real add would:

$ tui-do add --dry-run 'Call the dentist tomorrow +Personal *health !3 every week'
Would add "Call the dentist" to Personal, due Mon 9 Nov 2026
Parsed: title "Call the dentist" · +Personal · *health · !3 · due Mon 9 Nov 2026 · every week
as typed best: Call the dentist +Personal *health !3 due 2026-11-09 every week
Dry run: nothing was queued or sent.

It checks projects against the local store only: a project created elsewhere since the last sync can fail a dry run and still succeed for real, because a real add asks the server once before giving up. It also refuses a store that does not exist yet, or one a real run would first have to upgrade, rather than creating or changing it.

The best form is the title, then +project, *labels, @users and !N, then each date after its keyword in ISO form (due 2026-11-09, start 2026-11-09 at 09:00), then the repeat. Dates go last because of the rule above: a date leaves the title only when nothing follows it except whitespace, punctuation and other tokens. A date kept mid-sentence stays in the title, so the best form keeps it there and writes the date again at the end. Every real add whose line differs from its best form says so on a second line, as typed best: …; a line already written that way, spacing aside, gets no second line. A best form starting with - is shown after -- , which keeps it from being read as a flag when pasted back; the -- goes outside any quotes.

Wrap a name containing spaces in brackets or quotes; brackets are usually easier from a shell, which strips quotes before tui-do sees them:

tui-do add 'Renew the domain *urgent !3 +Admin tomorrow'
tui-do add 'File the quarterly return +[Life Admin] 27aug26'
tui-do add 'Water the plants every 3 days'

Run tui-do add with no text to be asked. At a terminal it opens a prompt a few lines tall at the bottom of the screen, not the full interface, so your scrollback stays put. An example in your own project and label names shows the recommended shape until the first key, and a line under the input shows what will be created, re-read on every key:

key
Tab Complete a +project, *label or @user from the local store, or a date word after due or start . A name with a space completes in brackets, +[Home Improvement]. A second Tab lists the matches
? Straight after + * @ !, after due or start , or on an empty line: list what can come next, without typing the ?. Anywhere else it is a question mark, because titles have them
F1 Every token
Enter Add it, exactly as tui-do add '<the line>' would
Esc, Ctrl-C Cancel, adding nothing

The interface's n prompt completes and answers ? the same way. Without a terminal, tui-do add with no text is the usage error it always was. The flags apply to the line it asks for, so tui-do add --dry-run alone asks, then checks what was typed and adds nothing.

Use single quotes, not double. At an interactive bash prompt, !3 is history expansion: the shell replaces it with an earlier command before tui-do sees the line, inside double quotes as readily as outside them. The task is then created with no priority and a stray word in its title, and nothing reports an error, because as far as tui-do is concerned that is what you typed. Measured: tui-do add "… !3 tomorrow" at a bash prompt became … exit tomorrow. zsh expands ! history references by default too. Single quotes suppress it, fish does not do this at all, and a non-interactive shell (a script, or an agent) has history expansion off regardless.

From the shell

tui-do add applies locally and queues for the server exactly as the interface does, so it works on a plane. It is also the way to use tui-do from a script: the interface itself needs a terminal on both stdin and stdout, and refuses to start, with a message saying which is missing, when either is redirected. Three flags matter:

  • --dry-run says what the line would add, and how it is best written, without adding it. It reads only the local store, so a project created since the last sync is unknown to it.
  • --create-labels creates any label the line names that does not exist yet. The interface asks instead of assuming. Without it, an unknown *label is left off and its words stay in the title as typed.
  • --offline skips the send entirely, but it needs a store that already knows your projects, because a task has to be filed somewhere. On a machine that has never synced you get "no project to add to". Without the flag tui-do add fetches the project list before it gives up, so run it once without --offline on a new machine (or start tui-do, which syncs at launch). After that it works on a plane as advertised.

A description goes beside the line, never in it. The quick-add line is the title and its tokens; the description is body text, stored exactly as given (Markdown, plain text or HTML), with no tokens read out of it. Pick one of three ways:

  • -d 'text' inline, for a line or two. The argument is kept byte for byte, newlines included.

  • --description-file PATH reads a file, and --description-file - reads stdin, for anything longer. A quoted heredoc moves several paragraphs without retyping or expanding them:

    tui-do add 'Write the plan +Work' --description-file - <<'EOF'
    ## Context
    
    What was tried, and what is left.
    EOF

    Run that from a script or type it where you are. Do not paste it into a terminal on another machine: pasted multi-line text often arrives re-indented, the closing EOF then no longer matches, and the shell waits at a > prompt with nothing added. To file a long description on a remote box, copy the file there (scp plan.md host:/tmp/plan.md) and use --description-file /tmp/plan.md.

  • --edit (-e) opens $VISUAL, else $EDITOR, else vi, the way git commit does. Everything from the # ---- >8 ---- scissors line down is ignored, as in git commit -v. Above it, blank lines at the start and just above the scissors are dropped and the rest is kept exactly, # Headings included. Leave it empty for no description, or quit with an error (:cq in vim) to add nothing. It needs a terminal.

It must be UTF-8 and at most 64 KiB. From a file, stdin or the editor, one trailing newline is dropped, since a file or a heredoc always ends in one, and CRLF becomes LF. The confirmation line counts it rather than printing it:

$ tui-do add 'Write the plan +Work due 2026-11-12' --description-file plan.md
Added "Write the plan" to Work, due Thu 12 Nov 2026, with a description (5 paragraphs, 114 characters)

Shell completions come in two kinds. Names — tui-do add Call the VA +Le then Tab offers +Legal — come from your local store, so the shell has to ask tui-do on every Tab. Add one line to your shell's startup file:

shell in add
bash ~/.bashrc source <(TUI_DO_COMPLETE=bash tui-do)
zsh ~/.zshrc, after compinit source <(TUI_DO_COMPLETE=zsh tui-do)
fish ~/.config/fish/config.fish TUI_DO_COMPLETE=fish tui-do | source

That completes +project, *label and @user from the store, a date word after due or start, and the flags and subcommands too. A name with a space comes out in brackets, +[Life Admin]. It reads the store and never writes, syncs or contacts a server, and with no store it offers nothing. It is generated on each shell start rather than saved, because the script and the binary speak a protocol that may change between versions.

It completes unquoted words. Inside a quoted '…' argument, what happens differs from shell to shell, and often nothing does. ? is not offered in a shell at all: only the tui-do add prompt has it. In bash a bracketed name goes in backslash-escaped, +\[Life\ Admin\], so it reaches tui-do as one word with its spacing intact; zsh and fish quote it themselves. An unquoted !3 is still bash history expansion, as above.

Name completion is the dynamic-completion cargo feature, on by default and in the release binaries. A build with --no-default-features ignores TUI_DO_COMPLETE; use the static script below there.

Flags only, from a file written once, still works as it always did:

tui-do completions fish > ~/.config/fish/completions/tui-do.fish
tui-do completions zsh  > ~/.zfunc/_tui-do          # with ~/.zfunc on $fpath
tui-do completions bash > ~/.local/share/bash-completion/completions/tui-do

For agents

tui-do add is a good target for automation. One line resolves a label, a priority, a project and a due date:

tui-do add 'Chase the upstream ticket *urgent !4 +Infra tomorrow'

Constructing the equivalent Vikunja request means knowing a project id, a label id, and that "unset" on the wire is Go's zero time rather than null.

It is also the right surface rather than merely a convenient one. The write lands in the local store first, so the command returns whether or not the server is reachable, and an unreachable server queues the task instead of losing it. It takes the same path the interface does: the same outbox, the same backoff, and the same three-way merge that replays your change onto the server's current copy. Something calling the Vikunja API directly is a second writer with none of that.

Learn the names with --tokens. tui-do add --tokens lists the projects, labels and users in the local store, one per line and grouped, each written the way a line should name it (+[Life Admin] for a project with a space), then the token syntax. It reads the store only, and fails with "run tui-do once to sync" if there is none yet.

Check generated lines with --dry-run first. It adds nothing and exits non-zero, with the message a real add would give, if the line would fail. Then write them the way the as typed best: line shows: title, then +project *label @user !N, then due YYYY-MM-DD, start YYYY-MM-DD and the repeat. That form reads the same way every time.

Put context in the description, through stdin. A stack trace, a spec or what was tried belongs in the description, not the title. Pass it with --description-file - and a heredoc whose delimiter is quoted (<<'EOF'), so nothing in it is shell-expanded, and keep the quick-add tokens on the title line, where they are read.

One flag deserves mentioning: --create-labels should usually stay off. Labels are one global pool shared by every project, so a typo in a generated line becomes a permanent entry that pollutes completion everywhere. Pass it only where the label vocabulary is yours rather than a model's.

Giving it to your agent

skills/tui-do/SKILL.md is the whole of this, written for a model: the tokens, --tokens, --dry-run, descriptions from stdin, and what a zero exit does and does not mean. It is plain Markdown in the Agent Skills format.

For Claude Code, install it as a personal skill, available in every project:

mkdir -p ~/.claude/skills/tui-do
curl -fsSL https://raw.githubusercontent.com/sjwasko/tui-do/v1.2.2/skills/tui-do/SKILL.md -o ~/.claude/skills/tui-do/SKILL.md

For an agent that reads AGENTS.md instead, save the file anywhere and add one line to the AGENTS.md of the project the agent works in:

To record a task or a follow-up, use `tui-do add`; read /path/to/tui-do/SKILL.md first.

The skill describes add as of the release it is fetched from, so fetch it from the tag you installed.

What verbs/actions to add for agents next?

Today add is the whole agent surface. Reading, completing and moving tasks from the command line are planned and not in this release, and which verbs get built is a democratic process. If you are driving tui-do from an agent, open an issue and say what you were trying to automate. That is worth more to me than a feature request in the abstract. Let's make this agentic together!

Kanban is the open design question. The list view is the only view today, and boards are planned. What an agent should say to move a task across a board — name a bucket, set a status, ask for "the next column" — is genuinely undecided, and it is the kind of thing that is easy to get wrong in a way you only notice after people depend on it. If you work in Vikunja's board views, I would like your opinion before it is built rather than after.

My vision on Kanban: scope an agent using a project or a label, dump a series of tasks into that project, arrange them in order, then have your agent start with that label or project and move tasks as they complete through the board. The project or label can become a very quick visual board for long-running, multi-step agentic tasks, instead of parsing through log files that differ by agent type in multiple terminal windows. How would you envision this being used?

Contributors and testers are welcome and needed. This project is small enough to be a reasonable first contribution and is not yet load-bearing for anyone, which makes it the perfect time in the project to try something and shape its future. Testing counts as much as code: running it against your own Vikunja, on your own hardware, and reporting what works, what doesn't, and what you need to be productive. Open an issue, not a PR (as mentioned).

What's Planned & Coming

1.0 is deliberately small: the foundation is the part I tried to get right. What follows is where tui-do goes next, and the order is not settled, which is exactly where I can use your help!

Coming

  • A real agent surface. add is the only action right now. Reading, completing, moving and searching from the command line turn tui-do into something an agent can actually operate rather than only write to. See For agents; this is the one I most want to talk to people about.
  • Disconnected mode. tui-do with no Vikunja behind it at all: a fast local task list that happens to speak Vikunja when there is a server to speak to. This is closer than it sounds, because the local store already answers every read and the server is already optional at startup. What is missing is making it optional permanently, and deciding what sync means if you later decide you do want to sync to a Vikunja server. But in my humble opinion, the app is pretty kick ass and you shouldn't need Vikunja if you want to use it standalone for your workflow.
  • Kanban, table and Gantt views, and saved filters. The list view is the only view currently. Boards are the most-asked-for and the least-designed; how an agent should express a move across one is an open question.
  • Comments. The API client can already do it; nothing in the interface reaches it yet. Future effort.
  • Subtasks and task relations. Vikunja's relation kinds are parsed and preserved on every write today, so the data survives; it is just not shown or editable. Future effort.
  • Windows, honestly. The answer is WSL and will stay WSL, but "use WSL" is a claim nobody has verified on a schedule. Making that a tested priority rather than an assumption is on the long list.

Deliberately not

  • Attachments. Out of scope. Existing attachments survive edits untouched; tui-do neither displays them nor uploads them.
  • Deleting a label. It cannot be undone honestly, because the label would come back with a new id detached from every task it was on. If it is ever built it gets a confirmation and a plain "this cannot be undone", not a broken undo.

Which of these first? That is a genuine question, not a rhetorical one: the order above is not a commitment and I would rather build what people will use than what I guessed at. Open an issue and say which one matters to you and why, or that the thing you want is not on the list at all. Volunteers to help build or test any of it are very welcome.

Platform support

Linux and macOS are supported.

  • Linux. Developed on Omarchy (Arch), with Ubuntu as the second target: built and tested against 26.04 in CI, and hand-driven on both 24.04 and 26.04 hardware, on x86-64 and aarch64 alike.
  • macOS. Apple Silicon only. The test suite runs on macOS in CI, and the interface is tested by hand on macOS 26 across several terminals, tmux, and over SSH from Linux. Installed with Homebrew or from the release tarball. Intel is not built.
  • Windows. Not a target. Use WSL and run the Linux build. There are no plans to ship a native Windows binary.

Building from source

Only needed to modify tui-do, or to run on an architecture no release covers. SQLite is compiled from source, so a C toolchain is required even though the resulting binary needs none. Rust 1.89 or newer.

On a fresh Debian or Ubuntu:

sudo apt-get update
sudo apt-get install -y --no-install-recommends \
    curl ca-certificates build-essential pkg-config git

# Take Rust from rustup rather than the distribution, which may package
# a version older than 1.89.
curl -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --default-toolchain stable
. "$HOME/.cargo/env"

On Arch: sudo pacman -S --needed rust base-devel git.

No OpenSSL development headers are needed: TLS is rustls, and ca-certificates is what it reads the system trust store from.

Then:

git clone https://github.com/sjwasko/tui-do.git
cd tui-do
cargo build --release
# `install -D` is GNU coreutils; BSD install (macOS) has no such flag.
mkdir -p ~/.local/bin
install -m755 target/release/tui-do ~/.local/bin/tui-do

The first build fetches and compiles the whole dependency tree and takes a few minutes.

Running the tests

cargo test --workspace

Read the total, not the last line. cargo test prints one test result: line per test binary (eighteen of them), and the last few are doc-test targets that legitimately contain no tests, so the output ends with 0 passed however well the run went. Summing them is what tells you:

cargo test --workspace 2>&1 | grep -E '^test result' | \
  awk '{p+=$4; f+=$6} END {print "passed="p"  failed="f}'

Anything but failed=0 is a real problem. cargo clippy --workspace --all-targets should also be silent.

Design

The render loop never awaits I/O. The UI is an Elm-style Model / Msg / update / view loop that is pure and synchronous. Side effects are described as values and executed by a separate async runtime that sends results back as messages.

This is enforced by the crate graph rather than by discipline:

Crate Responsibility Notably cannot
tui-do-api Typed go-vikunja REST client —
tui-do-core Domain model, SQLite store, sync engine, quick-add parser, config render
tui-do-ui Model, Msg, update, view, widgets, keymap perform I/O: no reqwest, no rusqlite, no tokio
tui-do CLI, wiring, effect runtime, terminal lifecycle —

Writes are optimistic: the local store updates immediately and the change is queued in an outbox. If the server rejects it, the change is rolled back and reported. A queued update is not sent as it was queued: the push reads the server's current copy and replays the user's field-level change onto it, because tui-do is built to run on several machines at once.

Every endpoint the client calls is checked against spec/vikunja.json (the OpenAPI document served by a live Vikunja at /api/v1/docs.json) by a conformance test, so an upstream API change surfaces as a failing test rather than a runtime 404.

Contributing

Issues are the way in. Please do not open a pull request without asking first.

This is not a formality, and it is not "PRs welcome" with extra steps; it is a fact about where the repository lives. GitHub is a read-only mirror. Development happens on a private Forgejo instance, and GitHub receives its commits by a push mirror, one direction only. A pull request opened here cannot be merged where the code actually lives, so a patch you spend an evening on would have to be re-applied by hand, and I would rather tell you that now than after you wrote it.

So:

  • Found a bug? Open an issue. Include your distribution, your Vikunja version, and what you expected instead. If tui-do printed something, paste it verbatim.
  • Want a feature? Open an issue describing the problem rather than the solution. What gets built first is decided by what people say they were trying to do; see What's Planned & Coming, which is a genuine list of open questions, not a roadmap already settled.
  • Want to send code? Open an issue first and say what you have in mind. If it is a fit, I will tell you how to get it to me. Small fixes are easy; anything touching the architecture is worth a conversation before you write it.

Your feedback is wanted first and foremost. See What verbs/actions to add for agents next?.

Relationship to cria

tui-do began as a fork-in-spirit of cria by frigidplatypus, which established the idea of a keyboard-driven Vikunja TUI along with its quick-add syntax and column-layout configuration. tui-do is an independent implementation with a different architecture and does not share cria's code.

Thank you

I wanted to take a moment to thank my wonderful wife Karrie for putting up with all the evening and weekend vibe coding sessions. Also, this is the product of Claude Code and multiple skills and is a first effort for me, so be kind and constructive. I very much enjoyed the architecture and build and hope to continue building and improving for all!

License

Licensed under either of

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Copyright is held collectively by the project's contributors ("The tui-do Authors"); attribution lives in the git history.

About

A fast, local-first terminal client for Vikunja

Topics

Resources

Contributing

Stars

13 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages