Sara — a folder-aware task manager
Sara is a personal assistant with a folder-aware task manager at its core. She
knows which Git project you're standing in, ranks your work with a transparent
urgency model, tracks time, and links tasks to branches.
Task data lives in a single SQLite database in your home directory — nothing is ever written into your repositories.
Table of contents
- Highlights
- Installation
- Quick start
- Core concepts
- The task list
- The detail view (
sara info) - Working with tasks
- The urgency model
- Configuration
- Inline Taskwarrior-style tokens
- Due dates
- Shell completions
- File locations
- Command reference
- Uninstall
Highlights
- Folder-aware —
saraauto-detects the current project (a Git repo, or any folder you runsara initin) and scopessara listto it by default. - Transparent urgency — a Taskwarrior-style scoring model decides ordering;
sara infoshows the exact breakdown. - Interactive TUI — a ratatui review form for adding/editing, and a rich detail view for everything else.
- Dependencies — block tasks on each other, with cycle detection and an at-a-glance
DEPScolumn. - Time tracking —
sara start/sara stopaccumulate active time, with optional estimates. - Git integration — tie a task to a branch and snapshot the files it touched.
- Full history — every change (field edits, deps, files, checklist, links, comments, timer) is recorded.
- Single SQLite file — easy to back up, and nothing is written into your repos.
Installation
The fastest paths use prebuilt packages and need no Rust toolchain. Prefer one of these; the from-source build further down is for development.
Quick install (Linux & macOS)
|
Downloads the right binary from the latest
GitHub Release into
~/.local/bin (override with SARA_INSTALL_DIR).
crates.io
Published as sara-tasks (sara and sara-cli were taken); the installed
binary is still sara.
Debian / Ubuntu (apt)
One-off .deb from a release:
Or add the apt repository so sudo apt install sara and future upgrades work:
|
Build from source
1 — Prerequisites
Rust (if not already installed):
|
# Restart your shell, or:
2 — Build & install
This compiles the binary and places it at ~/.cargo/bin/sara. Make sure
~/.cargo/bin is on your PATH (the Rust installer usually handles this):
Quick start
# Initialize the current folder as a Sara project.
# A git repo becomes its own project (named after the repo root); any other
# folder is initialized in place (named after the folder).
# Add a task (opens the interactive review form)
# Add quickly, no form, with an inline priority token
# See what to work on (current project, ranked by urgency)
# Inspect / edit a task interactively
# Start the clock, do the work, stop it
# Complete it
Core concepts
Projects. Every task belongs to a project. Inside a Git repo, sara uses
the repo as the project (run sara init once to record its goal/stack). In any
other folder, sara init registers that folder as the project, named after the
directory. The configurable default_project (inbox) is only used as a
last-resort fallback when a folder has no usable name.
IDs vs UUIDs. Each task has a small, recycled display ID (the 1, 2,
3 you type) and a stable UUID that never changes. Most commands accept
either the ID or a UUID prefix. When a task is completed, pending IDs are
repacked to stay small — so today's 4 may be tomorrow's 3.
Urgency. Tasks are ordered by a computed urgency score (see The urgency model). It rewards priority, due dates, active timers, tags, and tasks that block others — and penalizes blocked tasks.
The task list
sara list prints the pending tasks for the current project, highest urgency
first.
Each row has a small marker gutter, columns, and a dependency column:
⛓ 1 H web-app 2026-07-01 28.0 blocks 1 task Design the auth flow
Gutter markers (left edge):
| Marker | Meaning |
|---|---|
● |
Timer is running (task is active) |
♺ |
Recurring task |
⊘ |
Blocked — waiting on an unfinished task |
⛓ |
Blocking — other tasks depend on this one |
Columns: ID, PRI (H/M/L, color-coded), PROJECT, DUE (red overdue,
yellow soon), URG (urgency score), DEPS, and DESCRIPTION. A PR or ↗
badge appears before the description when the task has a linked pull request or
URL.
The DEPS column spells out the relationship the gutter hints at:
blocked by 3 (red) or blocks 2 tasks (gray).
Tip: set
NO_COLOR=1to disable colors (e.g. for piping or screenshots).
The detail view (sara info)
sara info <id> opens a full-screen, interactive view of a single task: all
fields, dependencies, attached files, links, comments, a checklist, the urgency
breakdown, a git panel, a project activity heatmap, and a live history log.
It's also where you edit a task inline.
Keys
| Key | Action |
|---|---|
↑ / ↓ (or k / j) |
Move between fields and items |
Enter / e |
Edit the selected field, or open the selected file/link |
← / → |
Cycle priority (when Priority is selected) |
Space |
Toggle the selected checklist item |
PgUp / PgDn |
Scroll |
Esc |
Cancel an edit |
q / Esc |
Close the view |
Editable fields: Description, Project, Priority, Due, Tags, Estimate, Recur, and Depends on.
To change dependencies, select Depends on, press Enter, and type the task
IDs it should wait on (space- or comma-separated), e.g. 7 9. sara reconciles
the set — adding and removing edges — and rejects self-references and cycles
with an inline error. The change is reflected immediately in the "Blocked by"
section and the History panel.
Non-interactive & agent-friendly output
sara info detects whether stdout is a terminal: in a TTY it opens the
interactive view; when piped it prints a readable plain-text digest instead.
You can force a specific format regardless of TTY:
| Flag | Output |
|---|---|
--md |
Markdown digest — LLM-native: ## headings and - [ ]/- [x] checkboxes for steps & acceptance. Ideal for agent context or a PR body. |
--plain |
The readable plain-text digest, forced (no TUI). |
--json |
The full structured guide (every field) for scripts. |
--history |
Include the full History log in --plain/--md (collapsed to a one-line summary by default to keep output lean). |
| The Markdown digest is the recommended way to feed a task to an AI agent: it's stable, omits the unbounded History log by default, and needs no reshaping.
Working with tasks
Adding tasks
By default sara add opens an interactive review form so you can confirm the
fields before saving. --yes saves immediately without the form. See
inline tokens for the project: / +tag /
pri: shorthand.
# …or set fields non-interactively (no TUI):
Dependencies
A dependency means "this task is blocked until that task is done." Blocked tasks sink in urgency; blocking tasks rise.
You can also edit dependencies interactively in the Depends on field of
sara info (see above). Dependencies are shown in sara list via the ⊘/⛓
gutter markers and the DEPS column. Cycles are prevented automatically.
Time tracking
Set an estimate (in the Estimate field of sara info) to see a progress
percentage against time spent. If a task is tied to a git branch, sara stop
snapshots the files changed on that branch.
Recurring tasks
Supported intervals: daily, weekly, monthly, yearly, or Nd / Nw /
Nm (e.g. 3d, 2w, 1m). Recurring tasks show a ♺ marker in the list.
Checklists
Break a task into sub-steps without creating separate tasks:
Add --kind acceptance to any sara step … command to act on the task's
acceptance criteria instead of its steps. Toggle items with Space in sara info.
Notes, comments & links
Linked PRs/URLs surface as a badge in sara list and are openable from sara info.
Git branch linkage
Note:
addbranchtakes the task ID, not a branch name — the branch is read from the repo you're standing in. The task's project must have beensara init'd inside that repo. Runsara stopafterwards to snapshot the changed files.
Sharing tasks
Export a task — together with its full dependency closure (the task plus every task it transitively depends on) — to a single copy-pasteable blob, then import it into another user's Sara on a different machine.
| What travels: the description, project, status, priority, due date, tags, estimate, recurrence, comments, checklist/steps, links and attached file paths — plus the dependency edges between the exported tasks. On import every task gets a fresh uuid and display id (so importing into a DB that already has the task never collides), dependency edges are remapped within the bundle, the timer is reset and urgency is recomputed. History and time-tracking do not travel.
A bundle carries each task's project name, not the project profile (its
goal, stack, conventions and setup/test/lint commands). Importing a task whose
project doesn't exist locally is fine — it's created under that name and shows up
in sara list/-p and tab-completion straight away; only the profile metadata
is absent. Run sara init in that project's folder to attach a profile, or use
-p/--project on import to drop everything into an existing local project
instead of the bundle's original name.
The blob tolerates being line-wrapped by email or chat clients, so a pasted
sara-task-v1:… token still imports even if it picked up newlines.
History & undo
Every mutating action is recorded and shown in the History panel of sara info:
field edits (description, project, priority, due, tags, estimate, recur, status),
timer start/stop, dependencies, attached files, checklist items, links, comments,
and branch ties. Additions show +, removals show −, and value changes show
old → new.
The urgency model
Urgency is a sum of weighted components, recomputed whenever a task changes.
sara info displays the exact breakdown, e.g.
28.0 (pri 6.0 + due 12.0 + blocking 8.0 + age 2.0).
| Component | Default | Applies when… |
|---|---|---|
priority_h |
6.0 |
Priority is High |
priority_m |
3.9 |
Priority is Medium |
priority_l |
1.8 |
Priority is Low |
due |
12.0 |
Scaled by closeness (overdue = full, 7+ days out = 0) |
blocking |
8.0 |
The task blocks at least one other task |
blocked |
-5.0 |
The task is blocked (penalty) |
active |
4.0 |
A timer is currently running |
has_tags |
1.0 |
The task has any tags |
project |
1.0 |
The task is not in the fallback project (inbox) |
age |
2.0 |
Scaled by age, capped at age_max days |
age_max |
365.0 |
Age in days at which the age bonus maxes out |
All coefficients are configurable under [urgency] in the config file.
Configuration
A config file is created with sensible defaults on first run.
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/sara/config.toml |
| Linux | ~/.config/sara/config.toml |
Full example:
= "inbox" # last-resort fallback name when a folder has no usable name
= "uk" # "uk" or "us" — affects "next friday" parsing
[] # all optional; defaults shown
= 6.0
= 3.9
= 1.8
= 12.0
= 8.0
= -5.0
= 4.0
= 1.0
= 1.0
= 2.0
= 365.0
Print the resolved config and database paths:
Inline Taskwarrior-style tokens
Leading and trailing tokens on sara add are parsed as attributes:
Tokens in the middle of a description stay as literal text. Explicit flags are always unambiguous and win over inline tokens:
| Token | Meaning |
|---|---|
project:x |
Set the project |
+tag |
Add a tag |
pri:H |
Set priority (H/M/L) |
Due dates
Natural-language dates work in the Due field of the review form and anywhere a
date is accepted:
| Input | Meaning |
|---|---|
2026-07-01 |
ISO date |
today |
Today |
tomorrow |
Tomorrow |
friday |
This coming Friday |
next friday |
Friday next week |
+3d |
3 days from now |
+2w |
2 weeks from now |
The date_dialect config setting (uk vs us) affects ambiguous phrasing.
Shell completions
Sara ships dynamic completions: once registered, <TAB> completes real
pending task ids — annotated with their descriptions — for commands like
sara done / info / start, and known project names for --project / -p.
Register by having your shell evaluate COMPLETE=<shell> sara at startup
(no fpath/compinit setup needed). Re-run on upgrade so the generated shell
glue stays in sync with the binary:
# Bash — ~/.bashrc
# Zsh — ~/.zshrc
# Fish
# Elvish
Restart your shell (or source the file) afterwards. To disable, set
COMPLETE= or COMPLETE=0.
Prefer a static completion script (command/flag structure only — no dynamic task-id/project values)?
sara completions <shell>still emits one, e.g.sara completions zsh > ~/.zsh/completions/_sara.
File locations
| What | macOS | Linux |
|---|---|---|
| Database | ~/Library/Application Support/sara/tasks.db |
~/.local/share/sara/tasks.db |
| Config | ~/Library/Application Support/sara/config.toml |
~/.config/sara/config.toml |
Run sara paths to see the exact locations on your machine.
Command reference
| Command | Description |
|---|---|
sara init |
Initialize/update the current folder as a project (--goal, --stack, --conventions, --notes, -y) |
sara add <desc> [tokens] |
Add a task (--yes, -p, --priority, -t, --every) |
sara list |
List tasks (-a all, -p/--project <name>) |
sara modify <id> |
Edit via the review form, or set fields non-interactively (--description, --priority, --due/--clear-due, --tag/--clear-tags) |
sara info <id> |
Open the interactive detail view (--md/--plain/--json, --history) |
sara done <id> |
Complete a task (--force if blocked) |
sara delete <id> |
Soft-delete a task (-y to skip confirmation) |
sara start <id> / sara stop <id> |
Start / stop the timer |
sara dep <id> on|off|list |
Manage dependencies |
sara check <id> <text> |
Add a checklist item |
sara step done|undone|remove <id> <n> |
Tick / reopen / delete step n (--kind acceptance) |
sara annotate <id> <text> |
Add a comment (alias comment); sara denotate <n> removes |
sara link <id> <url> |
Add a link; sara unlink <n> removes |
sara attach <id> <path> |
Attach a file path (alias pr) |
sara addbranch <id> |
Tie the current git branch to a task (--clear) |
sara export <id> |
Export a task + its deps to a portable blob (-o <file>) |
sara import [src] |
Import a task blob (file, arg, or stdin; -p <project>) |
sara activity |
GitHub-style activity heatmap (--project, -a) |
sara undo |
Revert the most recent command |
sara reset |
Delete a project's tasks and profile (-p, -y) |
sara paths |
Print config and data paths |
sara completions <shell> |
Generate shell completions |
Run sara help or sara <command> --help for full options.
Uninstall
Remove data and config:
# macOS
# Linux