[](https://github.com/p6laris/Void/releases)
[](LICENSE)
[](https://www.rust-lang.org/)
[](https://crates.io/crates/void-focus)
[](https://github.com/p6laris/Void/actions/workflows/ci.yml)
# Void
Void is a terminal focus timer for people who live in the shell. Pomodoro cycles, a real task queue, session history, and a few themes — all keyboard-driven, all stored locally.
Built with Rust, Ratatui, and Crossterm. Data lives in SQLite under `~/.local/share/void/void.db`. If you have an old `data.json`, it is imported once on first launch.
---
## 📸 Screenshots
**Dashboard** — timer, daily goal, active task, and today’s queue at a glance.
**Tasks** — priorities, tags, subtasks, filters, and search without leaving the list.
**Stats** — focus time, streaks, completed work, and a rolling activity chart.
---
## ✨ What you get
**Timer**
- Focus, Short Break, Long Break, and Custom modes
- Pomodoro cycle tracking that survives restarts
- Zen mode when you only want the clock and active task
- Optional sound and desktop notifications on session end
**Tasks**
- Due dates, tags, priority, time estimates, and status (Pending → In Progress → Done)
- Subtasks with a dedicated focus mode (`Tab` in, `q` out)
- Filters (All / Open / Done / Today / Archive), search, reorder, bulk actions
- Recurring tasks, dependencies, and auto-archive for old completed work
- CLI helpers: `void add`, `void list`, `void archive list`
**Stats & sessions**
- Total focus time, session counts, daily goal progress
- Streak tracking (daily, weekly, monthly)
- Recent session list with edit/delete
- Seven-day focus chart and task completion history
**Settings**
- Timer lengths, long-break interval, auto-start between phases
- Daily goal, idle pause, end-of-session warning
- Timer presets, task automation when all work is done
- Four built-in themes: Dark, Light, Polaris, Matrix
Everything writes to SQLite as you go. No cloud sync, no accounts.
---
## 📦 Install
### Pre-built binaries
Grab the latest archive for your platform from [GitHub Releases](https://github.com/p6laris/Void/releases).
| Linux (x86_64) | `void-linux-amd64.tar.gz` |
| macOS (Apple Silicon) | `void-macos-arm64.tar.gz` |
| macOS (Intel) | `void-macos-amd64.tar.gz` |
| Windows | `void-windows-amd64.zip` |
Unpack and put `void` on your `PATH`.
### Homebrew (tap)
Void ships through a personal tap today. CI updates it on every release:
```bash
brew tap p6laris/tap
brew install void
```
Formula: [p6laris/homebrew-tap](https://github.com/p6laris/homebrew-tap)
**Why not just `brew install void`?** That path is [Homebrew core](https://github.com/Homebrew/homebrew-core) — the main catalog on [formulae.brew.sh](https://formulae.brew.sh). Core needs a separate maintainer review (popularity, test coverage, build rules, and so on). The tap is the practical route for now: same `brew install` flow after one extra line.
You can have **both** later: core for `brew install void` with no tap, and the tap for pre-releases or faster updates. They are not mutually exclusive — just two different repos with two different submission processes. Core is not submitted yet.
> Release downloads must be public. A private GitHub repo will break installs for anyone outside the repo.
### Winget (Windows)
Once the package is accepted in [microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs):
```powershell
winget install p6laris.Void
```
Packaging runs automatically after releases; the first manifest still needs to land in winget-pkgs.
### Cargo
Requires Rust 1.70+.
```bash
cargo install void-focus
```
Or build from source:
```bash
git clone https://github.com/p6laris/Void.git
cd Void
cargo build --release
# binary: target/release/void
```
---
## ⌨️ Keyboard shortcuts
Press `5` or open **Help** inside the app for the full list. The important ones:
| Global | `Tab`, `1`–`5` | Switch views |
| Global | `q`, `Esc`, `Ctrl+C` | Quit (saves as you go) |
| Global | `Ctrl+S` | Export JSON backup |
| Timer | `s`, `Space` | Start / resume |
| Timer | `p` | Pause |
| Timer | `r` | Reset |
| Timer | `n` | Skip phase |
| Timer | `m` | Cycle mode |
| Timer | `z` | Zen mode |
| Tasks | `a` | Add task |
| Tasks | `c` | Add subtask |
| Tasks | `Tab` | Focus subtask list |
| Tasks | `Enter` | Cycle task status |
| Tasks | `Space` | Set active task |
| Tasks | `f` | Start focus on task |
| Tasks | `g` | Cycle filter |
| Tasks | `/` | Search |
| Tasks | `j` / `k` | Move selection |
Subtask focus: `j`/`k` navigate, `x` or `Enter` toggle, `-` remove, `q` back.
---
## 🎨 Themes
Open **Settings** (`4`), move to **Theme**, then cycle with `Enter`, `+`, `-`, or arrow keys.
| **Matrix** | Green on black (default) |
| **Dark** | High-contrast, easy on the eyes |
| **Light** | Bright terminals |
| **Polaris** | Cool blue palette |
Your choice is saved with everything else.
---
## 💾 Data & privacy
| Database | `~/.local/share/void/void.db` |
| Legacy import | `data.json` → migrated once to `data.json.migrated` |
| Backup | `Ctrl+S` or Settings → export JSON |
Void does not phone home. Tasks and sessions never leave your machine unless you copy the files yourself.
---
## 🛠 Development
```bash
cargo run # debug build
cargo test # unit tests
cargo fmt # format
cargo clippy -- -D warnings
```
Project layout:
```
src/
main.rs entry, CLI, event loop
app/ state, keys, popups, task/timer ops
ui/ Ratatui views (dashboard, tasks, stats, …)
storage.rs task & session logic
db/ SQLite schema, migrations, import/export
model.rs domain types
timer.rs timer state machine
theme/ built-in palettes + file-based themes
packaging/ Homebrew formula template, release assets
```
---
## 📄 License
MIT — see [LICENSE](LICENSE).