# tasu
[![Crates.io][crates-src]][crates-href]
[![CI][ci-src]][ci-href]
[![License][license-src]][license-href]
**A terminal todo list that ages.**
Tasks go into **today**. Whatever you don't finish sinks — today's leftovers
become **this week's**, and this week's become **later**. There are no due
dates, projects or tags; the list organizes itself by how fresh each task is.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mancuoj-collective/tasu/HEAD/assets/kanban-dark.svg">
<img alt="tasu — today / this week / later" src="https://raw.githubusercontent.com/mancuoj-collective/tasu/HEAD/assets/kanban-light.svg">
</picture>
## Install
Prebuilt binaries, no Rust toolchain needed.
**macOS / Linux**
```bash
brew install mancuoj/tap/tasu
```
Or without Homebrew:
```bash
**Windows (x86_64)** — in PowerShell:
```powershell
This installs `tasu.exe` into `%USERPROFILE%\.cargo\bin` and adds it to your
PATH; open a new terminal afterwards. Or download
[`tasu-x86_64-pc-windows-msvc.zip`](https://github.com/mancuoj-collective/tasu/releases/latest/download/tasu-x86_64-pc-windows-msvc.zip)
and put `tasu.exe` somewhere on your PATH.
**With Cargo** (Rust 1.88 or newer)
```bash
cargo install tasu
```
Or build from a checkout:
```bash
git clone https://github.com/mancuoj-collective/tasu.git
cd tasu
cargo install --path .
```
## Usage
```bash
tasu # open the app
tasu add "buy cat food" # record a task without opening the app
tasu list [today|week|later] # print the open tasks
tasu done "buy cat food" # complete a task
tasu drop "old idea" # drop (archive) a task
tasu move later "someday" # send a task to another bucket
tasu history [done|dropped] # print history (both views by default)
tasu config # print the data dir, config file and sync remote
tasu remote <url> # set the git sync remote (optional)
tasu sync # pull then push once, and report the result
tasu update # upgrade tasu the way it was installed
tasu completions bash # print a shell completion script
```
The everyday commands have short aliases, shown in `tasu --help`: `a` (add),
`ls` (list), `h` (history), `d` (done), `x` (drop), `mv` (move).
Every command that changes something prints what it did, and `list`, `history`
and `config` take `--json` for scripting.
Tasks carry no id, so `done`, `drop` and `move` match an open task by its
**exact title**; if none or several match, they error rather than guess.
`tasu update` detects how tasu was installed and runs the matching upgrade —
`brew upgrade mancuoj/tap/tasu`, the official installer, or `cargo install tasu`
— so the binary and the package manager that owns it stay in agreement. When it
cannot upgrade safely (an unknown install, or Windows, where a running `.exe`
cannot be replaced), it prints the exact command instead of guessing.
### Keys
| `j` `k` `↓` `↑` | move the cursor |
| `h` `l` `←` `→` | previous / next section |
| `g` `G` `Home` `End` | top / bottom |
| `space` `Enter` | complete |
| `a` | add (goes into today) |
| `e` | edit the title |
| `t` | move to today |
| `[` `]` | send to the nearer / farther bucket |
| `x` | drop (archive) |
| `c` | history |
| `?` | help |
| `!` | problem details |
| `q` `Esc` | quit |
| `Ctrl`+`c` | quit from anywhere |
Narrow terminals stack the buckets vertically; **100 columns or wider** lays
them out as three side-by-side columns.
`c` opens the history overlay. `Enter` restores a completed or dropped task to
its original bucket, `Tab` (or `←`/`→`) switches between _done_ and _dropped_,
and typing filters the list.
## FAQ
**Why is there no due date / project / tag / priority?**
Because the point is that you don't plan. Everything you capture lands in
_today_ and sinks on its own if you don't do it. Adding dates and projects turns
a two-second capture into a five-minute decision — the exact thing this app
exists to avoid.
**What happens if I edit on two machines at once?**
Try not to — tasu is a single writer (your work machine _or_ your home machine).
If they do diverge, the next sync merges the boards task by task instead of
getting stuck: tasks are matched by creation time, and a completed or dropped
copy wins over an open one. Nothing is lost, but a task you edited on both sides
may take its ordering from either machine.
**Is my data sent anywhere?**
No. There is no tasu server. With no remote configured tasu never even invokes
git; with one, your tasks go only to your own repository.
## Sync between machines (optional)
tasu is local-first: with no remote it never invokes git. Point it at a
**private** repository to sync, and it behaves like a single writer that commits
as you go.
```bash
tasu remote you/tasu-data # GitHub shorthand → https://github.com/you/tasu-data.git
tasu # next start clones / syncs
```
`tasu remote` accepts a full URL, an SSH address (`git@…`), a local path, or a
GitHub `owner/repo` shorthand. It verifies the remote **before** saving it; if
the check fails nothing is written (and any previous remote is cleared), so tasu
never gets stuck retrying an unreachable repository. With no argument it prints
the current remote, and `tasu remote --clear` turns syncing off.
- **First run** clones into an empty data directory. If the remote already has
history (say a README), tasu adopts it and pushes the local board on top.
- If **both sides** already have a board, they are merged task by task (matched
by creation time; a completed or dropped copy wins over an open one) — neither
machine loses tasks.
- **One branch** everywhere: the remote's default branch if it has one,
otherwise `main`. A machine's `init.defaultBranch` never leaks into the data
repo.
- In the app, tasu pulls on start and pushes a few seconds after each change
(debounced). A failure shows `✗ <reason> · ! details` in the footer; press
`!` for the whole git error. Quitting hands any last push to a detached
process and returns to the shell immediately.
- `tasu add` pulls before it reads and pushes after it writes, so a CLI-only
machine stays in sync too.
- Designed for **one writer at a time** (your work machine _or_ your home
machine). If the two do diverge, sync merges the boards task by task instead of
getting stuck on a conflict: tasks are matched by their creation time (stable
across renames), and a completed or dropped copy wins over an open one.
To try it against a local bare repository:
```bash
git init --bare /tmp/tasu-remote.git
TASU_DATA=/tmp/tasu-a TASU_REMOTE=/tmp/tasu-remote.git tasu add "from A"
TASU_DATA=/tmp/tasu-b TASU_REMOTE=/tmp/tasu-remote.git tasu add "from B" # clones A
TASU_DATA=/tmp/tasu-a TASU_REMOTE=/tmp/tasu-remote.git tasu add "back on A" # pulls B
git --git-dir /tmp/tasu-remote.git log --oneline
```
## Configuration
Environment variables take precedence over the config file. With no `remote`,
tasu never invokes git.
| Data directory | platform data dir `/tasu` | `TASU_DATA` | `data_dir` |
| Sync remote | none (local only) | `TASU_REMOTE` | `remote` |
The config file lives at `$XDG_CONFIG_HOME/tasu/config.json` (i.e.
`~/.config/tasu/config.json`):
```json
{
"data_dir": "/path/to/tasu-data",
"remote": "git@github.com:you/tasu-data.git"
}
```
It is kept **outside the data repository**, so it never travels between
machines (and a git checkout can never overwrite it).
## Non-goals
On purpose, there is no: due dates, projects, tags, priorities, subtasks,
notes, notifications, recurrence, global hotkey, or multi-writer merge.
## Development
```bash
cargo test
cargo clippy --all-targets --all-features -- -D warnings
```
The pure layers (domain, update, store, sync) are covered by unit and
end-to-end tests, including a real git round trip. To eyeball the layout without
a terminal, render sample boards to text, or regenerate the README screenshots as
SVG:
```bash
cargo run --example preview # text mock-ups of every screen
cargo run --example screenshot # writes assets/kanban-{light,dark}.svg
```
[`PRODUCT.md`](PRODUCT.md) is the product contract and
[`ARCHITECTURE.md`](ARCHITECTURE.md) describes how it is built.
## License
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).
[crates-src]: https://img.shields.io/crates/v/tasu?style=flat&colorA=18181b&colorB=1f6feb
[crates-href]: https://crates.io/crates/tasu
[ci-src]: https://img.shields.io/github/actions/workflow/status/mancuoj-collective/tasu/ci.yml?branch=main&style=flat&colorA=18181b&colorB=1f6feb&label=CI
[ci-href]: https://github.com/mancuoj-collective/tasu/actions/workflows/ci.yml
[license-src]: https://img.shields.io/github/license/mancuoj-collective/tasu?style=flat&colorA=18181b&colorB=1f6feb
[license-href]: https://github.com/mancuoj-collective/tasu/blob/main/LICENSE