Focus timer for the solo developer.
No distraction. No mercy.
ronin is a terminal-based focus timer built for developers who work alone. It runs Pomodoro-style sessions with bushido-flavored feedback: warrior acknowledgment when you finish, quiet shame when you quit early.
No GUI. No electron. No notifications popup. Just a countdown in your terminal and a quote at the end.
- Features
- Installation
- Quick Start
- Commands
- What Happens When You Quit
- Database
- Configuration & Data Location
- Development
- Related
- License
| Feature | Description |
|---|---|
| Pomodoro Timer | Configurable focus sessions with countdown display. |
| Rest Timer | Separate break timer with its own quote set. |
| Session Tracking | Every session (completed or abandoned) is logged locally. |
| Streak Counter | Track consecutive days of completed sessions. |
| Bushido Quotes | Curated warrior-themed feedback on completion and abandonment. |
| Zero Dependencies | Uses only Ruby standard library (pstore, optparse). |
| Offline Only | No network calls. No accounts. No telemetry. |
gem install ronin-focusgit clone https://github.com/YumaKakuya/ronin.git
cd ronin
gem build ronin-focus.gemspec
gem install ronin-focus-0.1.0.gem- Ruby >= 3.0.0
No external gems required.
# Start a 25-minute focus session
ronin focus
# Start a 45-minute focus session
ronin focus 45
# Take a 5-minute break
ronin rest
# See today's work
ronin statusExample output:
$ ronin focus
FOCUS — 25 min
Press Ctrl+C to abandon.
24:59 remaining
(25 minutes later...)
25 min complete.
A ronin does not need a master to keep his sword sharp.
ronin focus [minutes]- Default: 25 minutes
- Maximum: 240 minutes
- Sessions are recorded to the local database
- On completion: a warrior quote is displayed
- On
Ctrl+C: the session is logged as abandoned with a different quote
Examples:
ronin focus # 25 minutes
ronin focus 45 # 45 minutes
ronin focus 90 # 90 minutesronin rest [minutes]- Default: 5 minutes
- Rest sessions are not tracked in the database
- On completion: a brief transition quote
Examples:
ronin rest # 5 minutes
ronin rest 10 # 10 minutesronin statusShows all sessions for today with completion status.
Example output:
Today:
Completed: 3 sessions (75 min)
Abandoned: 1
[+] 09:15 — 25 min
[+] 10:00 — 25 min
[x] 11:30 — 25 min
[+] 14:00 — 25 min
[+]= completed[x]= abandoned (Ctrl+C)
ronin log [days]- Default: 7 days
- Shows per-day summary
Example output:
Last 7 days: 12 sessions, 300 min
------------------------------------
2026-04-24 3 sessions 75 min
2026-04-23 4 sessions 100 min
2026-04-22 2 sessions 50 min
2026-04-21 3 sessions 75 min
ronin streakShows your current streak of consecutive days with at least one completed session.
Example output:
Current streak: 4 days
All time: 47 sessions, 1175 min
If you press Ctrl+C during a focus session:
- The session is logged as abandoned
- A quote reminds you what just happened
^C
Musashi never walked away from a duel. You just did.
The abandoned session still appears in ronin status and ronin log. The data does not lie.
Sessions are stored in a local PStore database. Each session has the following structure:
| Field | Type | Description |
|---|---|---|
date |
String | ISO date (YYYY-MM-DD) |
started_at |
String | ISO 8601 timestamp |
duration |
Integer | Planned duration in minutes |
completed |
Boolean | Whether the session was completed |
| Platform | Path |
|---|---|
| Linux / macOS | ~/.config/ronin/sessions.db |
| Windows | %USERPROFILE%\.config\ronin\sessions.db |
The directory is created automatically on first run.
git clone https://github.com/YumaKakuya/ronin.git
cd roninruby -Ilib bin/ronin focus 1gem build ronin-focus.gemspec- zen-and-musashi — Japanese wisdom for your terminal
MIT License. See LICENSE for the full text.
A ronin does not need a master to keep his sword sharp.