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+).

cargo build
cargo run

For an optimized binary:

cargo build --release

The release executable will be created under target/release/.

You can also install directly:

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.