pomo.nvim

A simple yet powerful Pomodoro timer for Neovim, designed to keep you focused and productive without leaving your editor.

The UI is powered by morph.nvim, a React-like component library for Neovim buffers. The dashboard and the pomodoro list are reactive floating windows that update in real time.

Features

• Pomodoro Timer: Start timers for work sessions (pomodoros), short breaks, and long breaks.
• Reactive Dashboard: A floating panel rendered with morph.nvim that updates live every second — no manual refresh needed.
• Navigable Pomodoro List: Browse completed pomodoros with j/k, delete entries with d and confirm with y/n.
• Auto Cycle: Automatically start breaks and pomodoros in sequence.
• Daily Goals: Set a daily pomodoro goal to track your progress.
• Notifications: Receive notifications when starting, pausing, or completing a timer.
• Customizable: Adjust timer durations and define hooks to run your own functions on different events.
• Persistence: Timer state is saved and restored between Neovim sessions.
• Lualine Integration: Display the timer status directly in your status bar.

Requirements

• Neovim >= 0.9.0
• morph.nvim

Installation

lazy.nvim

{
    "4DRIAN0RTIZ/pomo.nvim",
    dependencies = { "jrop/morph.nvim" },
    cmd = {
        "PomoStart", "PomoStop", "Pomo", "PomoPause",
        "PomoShortBreak", "PomoLongBreak", "PomoToggleAutoCycle",
        "PomoView", "PomoSetGoal",
    },
    config = function()
        require("pomo").setup({
            -- your configuration here
        })
    end,
},

Usage

Commands

Command	Description
:Pomo	Toggle the live dashboard.
:PomoStart	Start a new pomodoro (prompts for a task description).
:PomoPause	Pause or resume the current timer.
:PomoShortBreak	Start a short break.
:PomoLongBreak	Start a long break.
:PomoView	Open the navigable list of completed pomodoros.
:PomoSetGoal <num>	Set your daily pomodoro goal. E.g., :PomoSetGoal 8.
:PomoToggleAutoCycle	Enable or disable automatic cycle of pomodoros and breaks.

Dashboard keybindings

When the dashboard is open:

Key	Action
s	Start pomodoro
p	Pause / Resume
b	Short break
l	Long break
a	Toggle auto-cycle
q	Close

Pomodoro list keybindings

When :PomoView is open:

Key	Action
j	Move down
k	Move up
d	Delete selected entry
y	Confirm deletion
n	Cancel deletion
q	Close

Suggested mappings

vim.keymap.set("n", "<leader>ps", "<cmd>PomoStart<cr>",  { desc = "Pomo: Start" })
vim.keymap.set("n", "<leader>pp", "<cmd>PomoPause<cr>",  { desc = "Pomo: Pause/Resume" })
vim.keymap.set("n", "<leader>pd", "<cmd>Pomo<cr>",       { desc = "Pomo: Dashboard" })
vim.keymap.set("n", "<leader>pv", "<cmd>PomoView<cr>",   { desc = "Pomo: View list" })

Configuration

Default values:

require("pomo").setup({
    timers = {
        pomodoro    = 25 * 60,  -- 25 minutes
        short_break =  5 * 60,  -- 5 minutes
        long_break  = 15 * 60,  -- 15 minutes
    },
    stages = {
        seed   = "🌱",  -- early stage of a pomodoro
        sprout = "🌿",  -- mid stage
        tree   = "🌳",  -- final stage
    },
    auto_cycle = false,        -- automatically chain pomodoros and breaks
    long_break_interval = 4,   -- pomodoros between long breaks
    hooks = {
        on_pomodoro_start = nil,
        on_pomodoro_end   = nil,
        on_break_start    = nil,
        on_break_end      = nil,
    },
})

Lualine integration

require("lualine").setup({
    sections = {
        lualine_x = {
            {
                require("pomo").get_lualine_status,
                cond = function()
                    return require("pomo").get_lualine_status() ~= ""
                end,
            },
        },
    },
})

Contributing

Contributions are welcome. If you have ideas, suggestions, or find a bug, please open an issue or submit a pull request.

License

MIT License.