# Void
Void is a polished terminal focus timer for people who want Pomodoro-style sessions, task management, progress tracking, and comfortable themes without leaving the keyboard.
It is built with Rust, Ratatui, and Crossterm. Your tasks, settings, theme choice, and session history are stored locally in SQLite (`~/.local/share/void/void.db`). Existing `data.json` files are imported automatically on first launch.
## Features
- Pomodoro workflow with Focus, Short Break, Long Break, and Custom timer modes.
- A dashboard with the current timer, active task progress, session cycle dots, daily goal progress, and quick stats.
- Task management with due dates, tags, priority, estimates, status cycling (Pending → In Progress → Done), filtering, search across title/notes/tags, reordering, and focus tracking.
- Stats view with total focus time, session counts, streaks, task history, and a seven-day focus chart.
- Settings view for timer lengths, daily goal, sound, notifications, auto-start behavior, active task selection, task automation, and themes.
- Zen mode for a distraction-free full-screen timer view with active task display.
- Persistent active task across restarts.
- Per-field SQLite writes (no debounced full sync).
- JSON export for backup (`Ctrl+S` or Settings → Export backup).
- Desktop notifications on session completion (configurable).
- Offline-first storage with local SQLite persistence.
## Themes
Void currently includes four built-in themes:
- `Dark` for a quiet high-contrast terminal look.
- `Light` for bright terminals and daytime use.
- `Polaris` for a cool blue focus palette.
- `Matrix` for a green-on-black hacker aesthetic (default).
Themes are wired into the interface through a shared palette, including foreground text, dim text, accent colors, status colors, timer progress colors, selected tab contrast, and the terminal background fill. The selected theme is saved with the rest of your app data and restored on launch.
To change the theme:
1. Open `Settings` with `Tab` or `4`.
2. Move to the `Theme` row with `Up` / `Down` or `j` / `k`.
3. Press `Enter`, `+`, `=`, `Right`, `-`, or `Left` to cycle themes.
## Views
`Dashboard` is the main working screen. It shows the timer, today’s progress, active task status, pending tasks, and useful shortcuts.
`Tasks` is where you manage your queue. You can assign priority, mark tasks for today, set an active task, search, filter, and reorder work.
`Stats` summarizes your focus history, completed tasks, pending work, streak, daily goal, and recent activity.
`Settings` lets you tune the app to your workflow, including timer lengths, auto-start behavior, sound, theme, and task automation.
`Help` lists the keyboard shortcuts inside the app.
## Keyboard Shortcuts
### Global
- `Tab` / `Shift+Tab`: switch views.
- `1` to `5`: jump to Dashboard, Tasks, Stats, Settings, or Help.
- `q`, `Esc`, or `Ctrl+C`: quit (data is saved as you go).
- `Ctrl+S`: export a `data.json` backup.
### Timer
- `s` or `Space`: start or resume.
- `p`: pause.
- `r`: reset.
- `n`: skip the current phase and log elapsed focus time when appropriate.
- `m`: cycle Focus, Short Break, Long Break, and Custom modes.
- `+` / `=`: increase the current timer duration.
- `-` / `_`: decrease the current timer duration.
- `z`: toggle zen mode.
### Tasks
- `a`: add a task.
- `e`: edit the selected task.
- `d`: delete the selected task.
- `Enter`: toggle done or pending.
- `Space`: set the selected task as active.
- `f`: start a focus session on the selected task.
- `t`: toggle the selected task in today’s queue.
- `g`: cycle task filters.
- `/`: search tasks.
- `1`, `2`, `3`: set Low, Medium, or High priority.
- `j` / `k` or `Up` / `Down`: move through the task list.
- `Ctrl+j` / `Ctrl+k`: reorder the selected task.
### Settings
- `Up` / `Down` or `j` / `k`: move between settings.
- `Enter`, `Right`, `+`, or `=`: toggle or increase a setting.
- `Left` or `-`: decrease a setting.
## Install And Run
Void requires a recent Rust toolchain (1.70+).
```bash
cargo build
cargo run
```
For an optimized binary:
```bash
cargo build --release
```
The release executable will be created under `target/release/`.
You can also install directly:
```bash
cargo install --path .
# or from crates.io:
cargo install void-focus
```
The installed command is `void`.
## Local Data
Void saves data through your operating system’s local data directory using the `dirs` crate. The app stores a SQLite database (`void.db`) under a `void` folder, containing tasks, timer settings, session history, daily goal progress, automation preferences, and the selected theme. If you have an older `data.json`, it is imported once on first run and renamed to `data.json.migrated`.
Void does not send task or session data over the network.
## Project Layout
- `src/main.rs`: terminal setup, event loop, drawing loop, and cleanup.
- `src/app.rs`: application state, keyboard handling, settings, theme palettes, and workflow logic.
- `src/ui.rs`: Ratatui rendering for dashboard, tasks, stats, settings, help, popups, and footer.
- `src/canvas_timer.rs`: canvas and compact timer visuals.
- `src/model.rs`: persisted data structures and domain types.
- `src/db/`: SQLite schema, migrations, and repository.
- `src/storage.rs`: task and session business logic.
- `src/timer.rs`: timer state and duration logic.
- `src/sound.rs`: completion sound and desktop notification helpers.
- `assets/void.jpg`: project image used by this README.
## License
Void is released under the MIT License. See `LICENSE` for details.