Ronin

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.

Table of Contents

Features

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.

Installation

gem install ronin-focus

From Source

git clone https://github.com/YumaKakuya/ronin.git
cd ronin
gem build ronin-focus.gemspec
gem install ronin-focus-0.1.0.gem

Requirements

  • Ruby >= 3.0.0

No external gems required.

Quick Start

# 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 status

Example 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.

Commands

focus — Start a Focus Session

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 minutes

rest — Take a Break

ronin 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 minutes

status — Today's Sessions

ronin status

Shows 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)

log — Session History

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

streak — Consecutive Days

ronin streak

Shows your current streak of consecutive days with at least one completed session.

Example output:

Current streak: 4 days
All time: 47 sessions, 1175 min

What Happens When You Quit

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.

Database

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

Configuration & Data Location

Platform Path
Linux / macOS ~/.config/ronin/sessions.db
Windows %USERPROFILE%\.config\ronin\sessions.db

The directory is created automatically on first run.

Development

Setup

git clone https://github.com/YumaKakuya/ronin.git
cd ronin

Running Locally

ruby -Ilib bin/ronin focus 1

Building the Gem

gem build ronin-focus.gemspec

License

MIT License. See LICENSE for the full text.

A ronin does not need a master to keep his sword sharp.