Skip to main content
This guide will get you up and running with Pomo quickly. You’ll start your first work session, learn the keyboard controls, and view your productivity statistics.
Make sure you’ve installed Pomo before continuing.

​
Your first work session

1

Start a default work session

Run Pomo with no arguments to start a 25-minute work session:
pomo
You’ll see the timer interface with ASCII art displaying the countdown:
╔════════════════════════════════════════════════════════╗
║                   WORK SESSION                         ║
╚════════════════════════════════════════════════════════╝

     ██████   █████            ██████   ██████  
    ░░██████ ░░███            ███░░███ ███░░███ 
     ░███░███ ░███           ░███ ░░░ ░███ ░███ 
     ░███░░███░███           ░░█████  ░███ ░███ 
     ░███ ░░██████            ░░░░███ ░███ ░███ 
     ░███  ░░█████            ███ ░███░░███ ███ 
     █████  ░░█████          ░░██████  ░░░█████  
    ░░░░░    ░░░░░            ░░░░░░     ░░░░░   

▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░░░░░░░░░░░░  2%

↑/k increase  Space pause  ←/h reset  s skip  q quit
2

Use keyboard controls

While the timer is running, try these keyboard shortcuts:
KeyAction
SpacePause/resume the timer
↑ or kAdd 1 minute to the current session
← or hReset to initial duration
sSkip to next session
q or Ctrl+CQuit
Try pausing the timer:
# Press Space to pause
# Press Space again to resume
3

Complete the session

Let the timer run down to zero (or press s to skip). When the work session completes, you’ll see a confirmation prompt:
Work session complete! What would you like to do next?

○ Start break session (5 minutes)
○ Start short session (2 minutes)  
○ Quit

y yes  n no  s short  Tab toggle  Enter submit  q quit
Press y or Enter to start your break session.
4

Take a break

The break session will start automatically:
pomo
# Complete work session → Press 'y' to start break
You’ll receive a desktop notification when the work session ends:
🎉 work finished
time to take a break

​
Custom session durations

You can override the default 25-minute work session with custom durations.
1

Start a custom work session

Specify a custom duration using Go’s duration format (1h, 30m, 90s):
pomo 45m
This starts a 45-minute work session with the default 5-minute break.
2

Customize both work and break

Provide two arguments to set both work and break durations:
pomo 50m 10m
This starts a 50-minute work session followed by a 10-minute break.
3

Start a break session directly

You can start a break session without doing work first:
pomo break
# Or with custom duration
pomo break 15m
Use 1h15m for 1 hour 15 minutes, or combine units like 90m (90 minutes). The format supports h (hours), m (minutes), and s (seconds).

​
Common usage patterns

Here are some common ways to use Pomo: 
# 25 min work + 5 min break (default)
pomo

​
View your statistics

After completing a few sessions, view your productivity statistics:
1

Open the stats view

pomo stats
You’ll see a full-screen statistics dashboard with:
  • Duration ratio - Total work time vs break time
  • Weekly bar chart - Work hours for each day of the past week
  • 4-month heatmap - GitHub-style activity visualization
2

Interpret the statistics

The stats view shows:
╔═══════════════════════════════════════════════════════╗
║              POMODORO STATISTICS                      ║
╚═══════════════════════════════════════════════════════╝

Duration Ratio
──────────────
Work:  2h 15m  ████████████████░░░░  75%
Break:   45m   ████░░░░░░░░░░░░░░░░  25%

Weekly Activity
───────────────
Mon  ████████░░░░░░░░  2.5h
Tue  ████████████░░░░  3.0h
Wed  ░░░░░░░░░░░░░░░░  0.0h
Thu  ████░░░░░░░░░░░░  1.0h
...
3

Exit the stats view

Press q or Ctrl+C to return to your terminal.
The heatmap visualization requires a Nerd Font installed. Without it, you may see placeholder characters instead of icons.

​
Long break cycles

By default, Pomo tracks your work sessions and automatically offers a longer break after every 4 completed work sessions. 
# Session 1-3: Work → 5 min break
# Session 4: Work → 20 min long break (default)
You’ll see a different prompt after your 4th session: 
Work session complete! Time for a long break!

○ Start long break (20 minutes)
○ Start short session (2 minutes)
○ Quit
Long breaks can be configured or disabled in the configuration file. The default is a 15-minute break after 4 work sessions.

​
Session summaries

When you complete or quit a session, Pomo displays a summary: 
╔═══════════════════════════════════════════════════════╗
║              SESSION SUMMARY                          ║
╚═══════════════════════════════════════════════════════╝

Session type:     work
Planned duration: 25m 0s
Actual duration:  23m 45s
Completed:        95%

Great focus session! 🎉

​
Next steps

Now that you’ve run your first sessions, explore more advanced features:

Work sessions

Learn about Pomodoro cycles, task chaining, and session management

Configuration

Customize default durations, notifications, and appearance

Keyboard shortcuts

Master all keyboard shortcuts for efficient timer control

Statistics

Deep dive into productivity tracking and analytics

​
Common issues

Make sure your system allows notifications from terminal applications. On macOS, check System Settings → Notifications. On Linux, ensure you have a notification daemon running.
Ensure your terminal supports 256 colors and UTF-8 encoding. Try a different terminal emulator or disable ASCII art in the configuration file.
If you installed via go install, ensure your $GOPATH/bin is in your $PATH:
export PATH="$PATH:$(go env GOPATH)/bin"
Add this to your .bashrc, .zshrc, or shell configuration file.
Install a Nerd Font and configure your terminal to use it. Popular choices include “Fira Code Nerd Font”, “JetBrains Mono Nerd Font”, or “Hack Nerd Font”.

Build docs developers (and LLMs) love

Get started for freeTalk to us