Your Flowtime control center, in the terminal.
A count-up focus timer that times and categorizes your breaks, plays the
focus-target / break-budget game, gamifies your day, and ships an interactive
in-terminal dashboard — raw ANSI, zero runtime bloat, instant cold start.
Built for humans and AI agents alike, like gh and vercel.
Pomodoro interrupts you every 25 minutes whether you're stuck or in deep flow. Flowtime counts up and gets out of the way — you pick one task, work until your focus naturally fades, log it, and take a break proportional to how long you worked. It respects your internal cognitive rhythm instead of fighting it.
flowclock turns that technique into a measurable, gamified system. The premise: what gets measured gets optimized. Track focus vs. rest, hit daily targets, keep streaks alive, and earn the dopamine of a rising flow score — so coming back to deep work becomes the path of least resistance.
| Flowtime (flowclock) | Pomodoro | |
|---|---|---|
| Work intervals | Variable — until focus fades | Fixed 25 min |
| Breaks | Proportional (~10–50% of work) | Fixed 5 min |
| Control | Internal — you decide | External — the timer decides |
| Best for | Deep, creative, unpredictable work | Repetitive tasks, procrastination |
It started as a production-proven Bash HUD used daily; this is the cross-platform, agent-native evolution that keeps that minimalist core and builds a whole productivity instrument around it.
npm install -g flowclock-cliRequires Node.js 20+. Works on Linux, macOS, and Windows (iTerm2, Kitty, Alacritty, Windows Terminal, GNOME Terminal, …).
flowclock # open the dashboard (default — v3)
flowclock start --goal "Deep work — StreamNet" \
--target 1h --break-budget 20m # start a session inside the dashboard
flowclock start --bare # standalone HUD, bypasses the dashboard
flowclock stats # flow score, ratio, streak, achievementsflowclock with no subcommand opens the interactive dashboard directly —
your Flowtime control center. From there you start, pause, take breaks, and stop
sessions without leaving the TUI. Use Tab or 1–6 to switch views.
flowclock start --bare opens a clean, centered standalone clock with a discreet
controls footer (bypassing the dashboard). In a normal TTY, flowclock start
routes you into the dashboard's Session hero view instead — same controls, richer
context. The HUD is also used for headless/--duration/non-TTY runs.
00:42:17
Ship v2 · 42m/1h ███████░░░ 70% break 06:00/20:00 · ratio 1:7.0
[p] pause [b] break [r] reset [q] stop
pquick pause/resume (a quick rest break)bstart/end a break — then1–6pick its category,ccyclesrreset ·q/Ctrl-Cstop & log
Prefer the old distraction-free clock? flowclock start --zen hides the footer
and progress entirely — just the time, nothing competing for your attention.
When you press b, the timer freezes your focus clock and starts counting the
break, suggesting a proportional length:
00:42:17
☕ BREAK · meal · 12:03 suggested 09:00
[1]rest [2]meal [3]exercise [4]walk [5]distraction [6]other [b] resume
Every break is logged with its category — so you can later see how much of your day went to meals vs. the gym vs. actual distraction, all measured against focus time.
The Flowtime "portion" method: commit to a block of focus and a budget of rest, then fill the focus while staying under the break budget.
flowclock start --goal "Deep work on StreamNet" --target 1h --break-budget 20mThe HUD tracks both live. Hit your focus target within the break budget and the
progress line earns a ✦ win marker. On stop you get a recap:
Focus 1h 02m 00s ✦ target met
Breaks 14m 30s (under 20m budget) — meal 12m, walk 02m 30s
Ratio 1:4.3 focus:rest
-
displayStyle— six looks for the big counter in the Session hero view, all sharing the same reserve-first scaling. Cycle live in the dashboard withd(orconfig set displayStyle …):block(default) — solid 7-segment glyphs.simple— clean heavy line digits in box-drawing strokes (┏━┓ ┃ ┣━┫ ┗━┛). Minimal and airy, but full hero size.outline— hollow silhouette of the block font rendered in DOUBLE-LINE box-drawing characters (╔═╗ ║ ╚╝): each digit is a distinctive double-walled nested-rectangle. Visually distinct fromminimalat every scale, including scale 1 (minimized windows).minimal— clean light line digits in box-drawing strokes (┌─┐ │ └─┘, airy○colon). Scales crisply at every size.classic— solid cornered "rounded-terminal" numerals (a distinct, stylized glyph shape), sharing the exact 5-row × 4-col footprint of every other style.bold— solid heavy-slab numerals (a distinct, heavier glyph shape), sharing the exact 5-row × 4-col footprint of every other style.
The goal sits centered above the counter and the focus/break metadata centered below it. Override the standalone HUD per session with
start --big.block simple outline ████ ████ ┏━━┓ ┏━━┓ ╔══╗ ╔══╗ █ █ █ █ ┃ ┃ ┃ ┃ ║ ║ ║ ║ █ █ █ █ ┃ ┃ ┃ ┃ ║ ║ ║ ║ ████ ████ ┗━━┛ ┗━━┛ ╚══╝ ╚══╝ minimal classic bold ┌──┐ ┌──┐ ██ ██ ████ ████ │ │ │ │ █ █ █ ██ █ ██ │ │ │ │ █ █ █ █ █ ███ └──┘ └──┘ █ █ █ █ ██ ██ ██ ███ ████ ████ -
Themes —
neon(default),amber,blue,mono. Set the default withflowclock config set theme amber, or override per session withstart --theme blue.
flowclock (no subcommand) or flowclock dashboard (aliases dash,
tui) opens the dashboard — the default entry point since v3. It's a
flicker-free, navigable control center built on a small in-house raw-ANSI TUI
(alt-screen + double-buffer diff renderer): zero new dependencies, same instant
feel. Open directly on a specific view with --view <name> (e.g.
flowclock dashboard --view help).
The dashboard has six views, navigable by Tab or the number keys:
| Key | View | Contents |
|---|---|---|
1 |
Session | Live session hero (big counter, goal, target progress, break budget, ratio, controls footer) |
2 |
Overview | Today's totals, flow-score gauge, daily goal, streaks, 7-day chart, achievements |
3 |
Sessions | Scrollable history + per-session focus/break timeline |
4 |
Goals | Per-goal rollups: focus time, count, hit/miss, target/budget |
5 |
Breaks | Time by category (meal/exercise/walk/…) and focus-vs-rest balance |
6 |
Help | Key bindings, view descriptions, and common workflows for newcomers |
The Session view hosts a live, interactive session inside the dashboard. The big 7-segment counter is scaled "reserve-first" — it gets ample vertical space before the surrounding metadata, so it never appears cramped:
Flowclock 12:23:28 [1:Session] 2:Overview 3:Sessions 4:Goals 5:Breaks 6:Help
╔══════════════════════════════════════════════════════════╗
║ Deep work — StreamNet ║
║ ║
║ ████ █ ████ ████ ██ ████ ║
║ █ █ ██ █ █ █ █ █ ║
║ █ █ █ ███ ███ ████ ██ ║
║ █ █ █ █ █ █ █ █ ║
║ ████ ███ ████ ████ █ ████ ║
║ ║
║ goal · 42m/1h ███████░░░ 70% break 06:00/20:00 · ratio 1:7.0 ║
╚══════════════════════════════════════════════════════════╝
[p] pause · [b] break · [c] cat · [e] edit · [x] cancel · [q] stop
The control row lives in the centered footer below the panel (trimmed to the
essentials so it fits and centers in a small terminal — [6] Help lists them all).
Live session controls inside the dashboard:
| Key | Action |
|---|---|
p |
Pause / resume |
b |
Start / end a break |
1–6 |
Pick a quick break category (rest · meal · exercise · walk · distraction · other) |
c |
Open the break-category picker — all categories, incl. coffee and sleep |
e |
Edit the running session — goal, details, focus target, break budget (timer keeps counting) |
x |
Cancel the session (discard without saving — confirmed first) |
r |
Reset the session clock |
z |
Zen — hide metadata, big clock only |
Enter |
Hide / show the control footer |
q |
Stop & save the session (a summary shows, then the Session view) |
q saves, x discards. The full category set is rest · meal · exercise · walk · distraction · other · coffee · sleep; keys 1–6 stay bound to the
first six so the footer stays short, and [c] opens a picker for the rest.
You no longer need to drop to the shell to start a tailored session. On the idle
Session view, press s, n, or Enter (or run start from the /
palette) to open a centered form:
╔══════════════════ New session ══════════════════╗
║ › Goal Deep work — StreamNet▏ ║
║ Details ║
║ Target 1h ║
║ Break budget 20m ║
║ ║
║ focus target — e.g. 1h, 90m, 25m (optional) ║
║ ║
║ [Tab] next · [Enter] start · [Esc] cancel ║
╚══════════════════════════════════════════════════╝
Tab / ↑↓ move between fields, Enter starts the session inside the dashboard,
Esc cancels. Durations accept the same forms as the CLI (1h30m, 90m, 25m,
45s, or bare seconds); an invalid value is reported inline rather than starting
the session. Every field is optional — an empty form starts a plain session.
The shell entry point still works and behaves identically:
flowclock start --goal "Deep work — StreamNet" --target 1h --break-budget 20mEvery text field is a real editor: move with ← →, Home/End, delete
around the cursor with Backspace/Del, and paste clipboard text
(multi-line pastes are flattened to one line). The same applies to the edit
overlays — [e] on the Sessions view (logged sessions) and [e] during a live
session (see below).
Sometimes you just want to start the clock before you've decided exactly what
you're doing. Begin a plain session, then press e at any point to open the
same form, pre-filled with the current goal, details, focus target and break
budget. Adjust anything, press Enter, and the changes apply without
stopping the timer — the session keeps counting and the crash-recovery journal
picks up the new metadata immediately. Esc discards the edit.
For a throwaway or test session you don't want recorded, press x. A
confirm overlay appears ([y] / [n]); confirming discards the session
entirely — nothing is written and the recovery journal is cleared. Use q
when you want to stop and save.
Hardware froze? Hard reset? While a session runs, FlowClock journals it to
~/.local/share/flowclock/active-session.json (on start, on each control
change, and on a ~5-second heartbeat). The next time you open the dashboard, an
orphaned journal triggers a resume prompt:
╔═══════════ Resume previous session? ════════════╗
║ A session was interrupted: ║
║ Deep work — StreamNet ║
║ details: CKIS Backup Session ║
║ ║
║ focus 3h 12m ║
║ break 0s ║
║ ║
║ [r] resume · [d] discard · [Esc] discard ║
╚══════════════════════════════════════════════════╝
[r] (or Enter) rebuilds the session and keeps going; [d] / Esc
discards it. Recovery is conservative — it restores to the last heartbeat
and never counts the frozen gap as focus, so at most a few seconds are lost. A
clean stop (q) or cancel (x) removes the journal, so you are only ever
prompted after a real crash.
The Session counter has six looks, all using the same reserve-first scaling so they stay prominent without overshadowing the metadata:
block(default) — solid 7-segment glyphs.simple— clean heavy line digits in box-drawing strokes (┏━┓ ┃); minimal but full hero size.outline— hollow silhouette of the block font rendered in DOUBLE-LINE box-drawing characters (╔═╗ ║ ╚╝): each digit is a distinctive double-walled nested-rectangle. Visually distinct fromminimalat every scale (including scale 1 / minimized windows).minimal— clean light line digits in box-drawing strokes (┌─┐ │), airy○colon. Scales crisply at every size; lighter feel thansimple.classic— solid cornered "rounded-terminal" numerals (a distinct, stylized glyph shape), sharing the exact 5-row × 4-col footprint of every other style.bold— solid heavy-slab numerals (a distinct, heavier glyph shape), sharing the exact 5-row × 4-col footprint of every other style.
Press d (or run display from the palette) to cycle
block → simple → outline → minimal → classic → bold, and t to cycle the
theme. Both choices are saved to your config as your new default — the same
as running config set displayStyle classic / config set theme neon. The
public default stays block; the rest are opt-in alternates. All six styles
share the same 5-row footprint — classic/bold are native distinct-shape
5-row fonts (cornered "rounded-terminal" classic / heavy-slab bold), so cycling
styles never changes the counter's size or covers the session goal.
While a session runs, the global footer is the single source of control hints (the panel no longer duplicates them):
z— zen: hide the goal + focus/break metadata, leaving just the hero clock.Enter— hide/show the controls row to remove visual noise once memorised.ppause ·bbreak ·1–6category ·rreset ·qstop & save.
On the Sessions list, e opens an Edit-session overlay to change the
focus duration, break total, goal, or name for the selected session; the start
timestamp is immutable and the end + break timeline recompute automatically.
Supr/Delete opens a confirmation modal
([y] confirm · [n] cancel) to delete the selected session from sessions.json.
Press / to open a transient, centered command-palette overlay. It is not
a permanent bar — it appears only when invoked and disappears when you press
Esc or select a command, keeping the dashboard chrome minimal.
[Tab] / [1–6] switch view [↑↓] / [j k] scroll
[s] / [n] new session [Enter] detail / start · hide controls (live)
[d] display style [t] theme (both saved)
[z] zen (live) [Supr] delete session (Sessions · confirm)
[e] edit session (Sessions · focus/break/goal/name)
[/] command palette [r] refresh
[q] / [Esc] quit / close overlay
The dashboard restores your terminal cleanly on exit — no artifacts.
flowclock dashboard --json # emits DashboardSnapshot, never launches the TUI Flowclock 12:23:28 [1:Overview] 2:Sessions 3:Goals 4:Breaks
┌─ Today ───────────────────────┐ ┌─ Flow ──────────────────────────────┐
│ Focus 1h 45m 2 sessions │ │ Flow score ████████░░░░ 58/100 │
│ Break 12m ratio 8.8:1│ │ Daily goal ████░░░░░░░░ 44% (4h) │
│ Streak 1 day (best 1) │ │ Achievements First Hour · Budget … │
└───────────────────────────────┘ └─────────────────────────────────────┘
┌─ Last 7 days ───────────────────────────────────────────────────────────┐
│ Mon Tue Wed Thu Fri Sat Sun │
│ ▁ ▁ ▁ ▁ ▁ ▁ █ 1h 45m today │
└──────────────────────────────────────────────────────────────────────────┘
[Tab] view · [↑↓] move · [Enter] detail · [r] refresh · [q] quit
flowclock stats turns your log into a scoreboard:
Today 1h 45m 00s (2 sessions)
Best 55m 00s
Streak 1 day (best 1)
Flow Score 58/100
Daily Goal 44% (1h 45m 00s of 4h 00m 00s)
Focus:Rest 8.8:1 today (12m 00s break)
Achievements First Hour, Budget Master, Flow 4:1
- Flow score (0–100) — a composite of focus volume vs. your daily goal, a healthy focus:rest balance, and your streak.
- Daily maximization — focus time vs.
dailyFocusGoalS(default 4h): how much of your target day you captured. - Streaks — current and longest run of consecutive days with ≥1 session.
- Achievements — First Hour, Deep Diver (90m+ single focus), Budget Master, Flow 4:1, Streak 7, Century.
flowclock summary --week # this week
flowclock summary --week 2026-23 # a specific ISO week### Week 2026-W24
| Date | Sessions | Total | Best | Break | Ratio | Goal |
| ---- | -------- | ----- | ---- | ----- | ----- | ---- |
| 2026-06-09 | 2 | 1h 45m 00s | 55m 00s | 12m 00s | 8.8:1 | Ship v2 |
| **Total** | **2** | **1h 45m 00s** | | **12m 00s** | | |Every interactive flow has a non-interactive equivalent, so terminal AI agents (Claude Code, Codex, Gemini CLI, and friends) can drive flowclock without a TTY:
flowclock log --duration 3000 --goal "Deep work" \
--details "CKIS backup" --target 1h --break-budget 20m --json # record a full session
flowclock edit <id> --focus 90m --details "renamed" --json # fix a session that ran while you slept
flowclock dashboard --json | jq .data.game # the whole snapshot, no TTY
flowclock stats --json | jq .data.game.flowScore # compose with pipes
echo "$SESSION_JSON" | flowclock log --json # accept session JSON on stdin
flowclock manifest --json # discover every command
flowclock mcp # MCP server over stdio--jsonon every command, with a stable, versioned envelope.flowclock edit— the start timestamp is immutable; end and the break timeline recompute automatically from the new focus + break values.--yesskips prompts;--no-color/NO_COLORfor clean output.- Deterministic exit codes (below) — the contract agents branch on.
- No hidden TTY requirements: non-TTY runs default to machine-friendly mode; the dashboard emits a JSON snapshot instead of launching the UI.
- MCP server exposes
flowclock_stats,flowclock_history,flowclock_log,flowclock_dashboard,flowclock_config_get/set, andflowclock_doctor.
| Code | Meaning |
|---|---|
| 0 | OK |
| 1 | Generic error |
| 2 | Invalid arguments / usage |
| 3 | Configuration error |
| 4 | Session data unreadable/corrupt |
| 5 | Interactive flow required but no TTY (use --duration/--json) |
| 6 | A doctor check failed |
Stored at config.json in your config dir (flowclock config path). Keys:
| Key | Default | Meaning |
|---|---|---|
theme |
neon |
neon · amber · blue · mono |
displayStyle |
block |
Counter look: block solid (default), simple heavy line digits, outline hollow silhouette in double-line chars (╔═╗) distinct from minimal, minimal light line digits, classic cornered/rounded solid numerals (distinct shape), bold heavy-slab solid numerals (distinct shape) — all share the exact 5-row footprint; cycle live with d |
showControls |
true |
show the controls footer (--zen overrides) |
dailyFocusGoalS |
14400 |
daily focus goal in seconds (drives maximization %) |
keybindings.{pause,break,category,reset,quit} |
p b c r q |
in-session keys |
sessionsPath |
null |
override sessions.json location |
apiEndpoint |
null |
optional JSON push endpoint (roadmap) |
Override locations with FLOWCLOCK_CONFIG_DIR / FLOWCLOCK_DATA_DIR. Sessions are
appended silently to sessions.json (atomic writes, corrupt-file recovery). Old
v1/v2 files load unchanged — legacy pauses are migrated to categorized breaks
on read.
A session records active focus seconds (durationS) plus categorized
breaks (each with category ∈ rest·meal·exercise·walk·distraction·other·coffee·sleep),
the total breakS, and the optional focusTargetS / breakBudgetS you set. The
on-disk schema is v3; migrations are non-destructive.
| Version | Focus |
|---|---|
| v0.1.0 ✅ | Core HUD, silent logging, stats/history/config/doctor, agent-native layer, MCP server |
| v1.0.0 ✅ | Goals mode, daily streaks, theme override + --big, weekly export, shell completions, schema v2 |
| v2.0.0 ✅ | Flowtime break model (categories), targets + break budgets, proportional breaks, gamification (flow score/achievements), interactive TUI dashboard, visible controls + --zen, schema v3 |
| v3.0.0 ✅ | Dashboard as default command; Session hero view (big balanced counter, live controls); Help view; / command palette; start --bare; dashboard --view; live theme switching; reserve-first counter scaling |
| v3.1.0 ✅ | In-dashboard new-session form (goal/name/target/break); live + persisted display-style (d) and theme (t) toggles; scaled minimal simple style (shares block's scaling) |
| v3.2.0 ✅ | simple reworked into a clean line font; outline added as a third selectable style; display-style toggle fixed on small/tiled windows |
| v3.3.0 ✅ | classic + bold terminal-style counter fonts; outline rewritten as clean line-art (fixes small/medium rendering); centered session layout; z zen + Enter hide-controls; delete a session from the dashboard (confirm modal); deduped controls footer |
| v3.3.1 ✅ | outline redrawn as a light seven-segment font (no more garbling at large scale); classic/bold degrade gracefully (drop goal line → block font) instead of collapsing to a text clock in a minimized window with metadata |
| v3.4.0 ✅ | restored the original silhouette outline style (hollow double-wall nested-rectangle); added minimal (light seven-segment line font); uniform counter scaling so classic/bold no longer tower over the 5-row fonts in minimized/zen windows |
| v3.4.1 ✅ | outline double-line box-drawing chars (╔═╗) — distinct from minimal at every scale; uniform classic/bold footprint — height capped to 5-row reference, degrades to block in short windows |
| v3.5.0 ✅ | classic/bold redesigned as 5-row shade weights (▒/▓) for exact footprint parity with all styles — no more towering, goal covering, or silent fallback to block |
| v3.5.1 ✅ | classic lightened to ░ shade so block █ / classic ░ / bold ▓ read as three distinct surfaces while keeping exact 5-row footprint parity |
| v3.6.0 ✅ | classic/bold redesigned as native 5-row fonts with distinct glyph shapes (cornered classic / heavy-slab bold, both solid) — replaces the v3.5.x shade-fill approach so the three solid styles read as clearly distinct while keeping exact footprint parity |
| v3.7.0 ✅ | Session editing — in-dashboard [e] overlay (view 3 · Sessions) and flowclock edit <id> CLI; editable fields: focus, break total, goal, details; start immutable; end + break timeline recompute automatically |
| v3.8.0 ✅ | Crash recovery (resume an interrupted session); [x] cancel-without-saving; coffee + sleep break categories with a picker; full line editors (cursor + paste) in every text field; "Name" → "Details" (CLI --details, --name/--label kept as aliases) |
| v3.9.0 ✅ | Edit a running session with [e] (goal/details/target/budget, timer keeps counting); break-category picker moved to [c] (was [m] more); centered, compact session footer; header reads Flowclock (dropped the "Dashboard" suffix) |
| next | flowclock sync — push sessions.json to a self-hosted/cloud endpoint; recurring goals; dashboard filters |
| later | Per-goal analytics deep-dives, calendar heatmap, Homebrew tap |
See CONTRIBUTING.md. The short version: branch from main, add
tests, keep the HUD instant and dependency-free, and make sure
npm run build && npm test && npm run lint && npm run typecheck all pass before
opening a PR.
flowclock-cli is dual-licensed — this is final:
- Open source: GNU AGPL-3.0 (or later). Free for everyone; the code stays open. The AGPL's network clause keeps hosted forks open too.
- Commercial: LICENSE-COMMERCIAL — for companies that want to embed or resell flowclock without AGPL obligations.
MIT/Apache are deliberately not used: they would let a company resell the work without a commercial agreement. The dual model keeps it free for the public while reserving commercial rights for the author.
Part of the Korvex agent-native developer-tool suite, alongside recmp3-cli.