Farora

A local-first, plain-text task tracker with a Textual TUI.

Tasks live as Markdown files with YAML frontmatter in a plain folder, so they sync over any file-sync engine, diff cleanly in git, and stay readable without Farora.

Install

Use a recent uv — it provisions Python 3.14 for you:

uv self update             # or: brew upgrade uv

uvx farora                 # run without installing
uv tool install farora     # install persistently

Because the current Python version (3.12.9) does not satisfy Python>=3.14 and
farora==0.5.0 depends on Python>=3.14, we can conclude that farora==0.5.0
cannot be used.

uvx --python 3.14 farora
uv tool install --python 3.14 farora

Supported configuration

Farora 0.5 is developed and tested on macOS with Python 3.14+. uv provisions the interpreter for you.

These tools are optional — each unlocks a feature, and Farora degrades cleanly without it:

Linux and Windows are not supported in this release.

Commands

All commands accept --repo PATH, defaulting to $FARORA_REPO, else ~/.farora.

Deleted tasks are kept before they are gone

Deleting a task removes its tasks/FAR-42.md, but its journal stays behind as a tombstone holding a full snapshot of the task — frontmatter and body text. That is what u undoes a delete from, and what a future farora restore would rebuild from.

So a deleted task's text is still readable in the repo, in projects/FAR/journal/FAR-42.jsonl, until garbage collection removes it. If a task held something sensitive, deleting it is not the same as shredding it — anything syncing or backing up the folder has the snapshot too.

Garbage collection runs opportunistically: every ordinary farora run sweeps the repo it opens, so there is no daemon and nothing to schedule. Tombstones older than the retention window are purged; everything else — every live task, and every tombstone still inside the window — is left alone.

farora gc                      # purge now, using the configured window
farora gc --older-than 0s      # purge every tombstone, right now
farora gc --older-than 7d      # ... or everything deleted over a week ago

Configure it in ~/.config/farora/config.toml:

[gc]
enabled   = true    # false: never sweep on ordinary runs (`farora gc` still works)
retention = "30d"   # how long a deleted task's snapshot is kept: s | m | h | d | w

Both keys are optional and the values above are the defaults. Purging is permanent: once a tombstone is collected, undo and restore have nothing to work from, and the task number is never reused.

License

Proprietary. See LICENSE.

Free to use for any purpose, including commercially — by individuals and by companies, at no charge and without asking. Redistribution and modification are not permitted.

To license Farora on other terms, contact hi@farora.tools.