{"id":46831049,"url":"https://github.com/lambertse/nvim-pomodoro","last_synced_at":"2026-03-11T11:01:03.399Z","repository":{"id":342307971,"uuid":"1173254829","full_name":"lambertse/nvim-pomodoro","owner":"lambertse","description":"Pomodoro timer for Neovim written in Lua","archived":false,"fork":false,"pushed_at":"2026-03-10T09:20:31.000Z","size":8629,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-10T15:47:36.477Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lambertse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-05T06:59:30.000Z","updated_at":"2026-03-10T09:20:34.000Z","dependencies_parsed_at":"2026-03-11T11:00:52.599Z","dependency_job_id":null,"html_url":"https://github.com/lambertse/nvim-pomodoro","commit_stats":null,"previous_names":["lambertse/nvim-pomodoro"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/lambertse/nvim-pomodoro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambertse%2Fnvim-pomodoro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambertse%2Fnvim-pomodoro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambertse%2Fnvim-pomodoro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambertse%2Fnvim-pomodoro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lambertse","download_url":"https://codeload.github.com/lambertse/nvim-pomodoro/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambertse%2Fnvim-pomodoro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30379264,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T06:09:32.197Z","status":"ssl_error","status_checked_at":"2026-03-11T06:09:17.086Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-10T10:01:04.910Z","updated_at":"2026-03-11T11:01:03.350Z","avatar_url":"https://github.com/lambertse.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🍅 nvim-pomodoro\n\n**A Pomodoro timer for Neovim, written purely in Lua.**\n\n![Neovim](https://img.shields.io/badge/Neovim-0.9%2B-57A143?style=flat-square\u0026logo=neovim\u0026logoColor=white)\n![Lua](https://img.shields.io/badge/Lua-100%25-2C2D72?style=flat-square\u0026logo=lua\u0026logoColor=white)\n![License](https://img.shields.io/github/license/lambertse/nvim-pomodoro?style=flat-square)\n\n\u003c/div\u003e\n\n---\n\n## 📸 Screenshots\n\n\u003e **Popup — Focus session running**\n\u003e \n\u003e ![screenshot-focus](assets/focus-time.png)\n\n\u003e **Popup — Short Break**\n\u003e\n\u003e ![screenshot-break](assets/short-break.png)\n\n---\n\n\u003c!-- ## 🎬 Demo --\u003e\n\u003c!----\u003e\n\u003c!-- \u003e ![demo](assets/demo.gif) --\u003e\n\n---\n\n## ✨ Features\n\n- 🍅 **Focus / Short Break / Long Break** sessions with automatic cycling\n- 🔢 **Big-digit clock** rendered in Unicode block characters, colour-animated every second\n- 🎨 **Per-session tab colours** (red for Focus, green for Short Break, blue for Long Break)\n- ⏸ **Pause \u0026 Resume** — pick up exactly where you left off\n- 🔔 **Milestone notifications** at 5 min, 1 min and 30 s remaining (stays on screen for 8 s)\n- 🪟 **Detach mode** — close the popup while the timer keeps running in the background\n- ⌨️ **Keyboard-first UI** — every action reachable without leaving the home row\n- 💤 **Zero dependencies** — pure Lua, uses only `vim.loop` (libuv already in Neovim)\n- 🎵 Sound **optional** via `vim.notify` (works with `nvim-notify` if installed, or any custom `vim.notify` implementation) **(CURRENTLY ONLY SUPPORT MACOS)**\n- ⚡ **Blurred background** (optional) to help you focus on the timer and block out distractions\n---\n\n## 📦 Installation\n\n### [lazy.nvim](https://github.com/folke/lazy.nvim)\n\n```lua\n{\n  \"lambertse/nvim-pomodoro\",\n  config = function()\n    require(\"nvim-pomodoro\").setup({\n      -- config options here, or leave empty to use defaults\n    })\n  end,\n}\n```\n\n### [packer.nvim](https://github.com/wbthomason/packer.nvim)\n\n```lua\nuse {\n  \"lambertse/nvim-pomodoro\",\n  config = function()\n    require(\"nvim-pomodoro\").setup({\n      -- config options here, or leave empty to use defaults\n    })\n  end,\n}\n```\n\n---\n\n## ⚙️ Configuration\n\nCall `setup()` with any overrides — all fields are optional and fall back to the defaults shown below:\n\n```lua\nrequire(\"nvim-pomodoro\").setup({\n  focus_time               = 25,   -- minutes\n  break_time               = 5,    -- minutes\n  long_break_time          = 15,   -- minutes\n  cycles_before_long_break = 4,    -- focus sessions before a long break\n  keymap                   = \"\u003cleader\u003ep\",\n  sound = {\n    enabled          = true,\n    volume           = 0.7,\n    backend          = \"auto\",\n    events = {\n      start     = true,\n      done      = true,\n      milestone = true,\n      tick      = false,\n      urgent    = true,  -- For the final 10 seconds of a session\n    },\n    files = {\n      start     = \"/System/Library/Sounds/Glass.aiff\",\n      done      = \"/System/Library/Sounds/Hero.aiff\",\n      milestone = \"/System/Library/Sounds/Tink.aiff\",\n      tick      = \"/System/Library/Sounds/Basso.aiff\",\n      urgent    = \"/System/Library/Sounds/Glass.aiff\",\n    },\n  },\n})\n```\n\n---\n\n## 🖥️ Usage\n\n| Method | Action |\n|--------|--------|\n| `:Pomodoro` | Open / close the Pomodoro popup |\n| `\u003cleader\u003ep` (default) | Toggle the popup |\n\n### Popup keymaps\n\n| Key | Action |\n|-----|--------|\n| `s` | Start / Pause the current session |\n| `r` | Restart the current session from the beginning |\n| `\u003cTab\u003e` | Cycle to the next mode (Focus → Short Break → Long Break → …) |\n| `\u003cS-Tab\u003e` | Cycle to the previous mode |\n| `1` | Switch to Focus |\n| `2` | Switch to Short Break |\n| `3` | Switch to Long Break |\n| `q` / `\u003cEsc\u003e` | Detach — hide popup, timer keeps running |\n| `x` | Close — hide popup **and** stop the timer |\n\n---\n\n## 🔔 Notifications\n\nAutomatic reminders fire once per session at:\n\n| Time remaining | Message |\n|----------------|---------|\n| 5 minutes | ⏳ 5 minutes left! |\n| 1 minute | ⚡ 1 minute left! |\n| 30 seconds | 🔔 30 seconds left! |\n| Final 10 seconds | 🚨 Time's almost up! \u0026 sound |\n\nWorks with the built-in `vim.notify` and enhanced with [nvim-notify](https://github.com/rcarriga/nvim-notify) if installed.\n\n---\n\n## 🏗️ Project Structure\n\n```\nnvim-pomodoro/\n├── README.md\n├── LICENSE\n└── lua/\n    └── nvim-pomodoro/\n        ├── init.lua              -- Entry point: setup(), M._initialized guard,\n        ├── config.lua            -- Default options, deep merge helper,\n        ├── timer.lua             -- Core timer: vim.loop uv handle, start/stop/pause/resume,\n        ├── notify.lua            -- Session-end notifications via vim.notify,\n        ├── ui.lua                -- Floating popup, backdrop dim window,\n        └── sound/\n            ├── init.lua          -- Public API: sound.setup(), sound.play(), sound.toggle(),\n            └── backend/\n                ├── macos.lua     -- afplay via vim.loop.spawn, skip-if\n```\n\n---\n\n## 🎨 Highlight Groups\n\nOverride any of these in your colorscheme or `init.lua`:\n\n| Group | Default | Used for |\n|-------|---------|----------|\n| `PomodoroTabFocus` | red bg | Active Focus tab |\n| `PomodoroTabShort` | green bg | Active Short Break tab |\n| `PomodoroTabLong` | sapphire bg | Active Long Break tab |\n| `PomodoroTabInactive` | muted fg | Inactive tabs |\n| `PomodoroClockPulse` | cycles 7 colours | Big-digit clock (animated) |\n| `PomodoroRunning` | green fg | `▶  Running` status |\n| `PomorodoPaused` | peach fg | `⏸  Paused` status |\n| `PomodoroHintKey` | mauve fg | `[key]` portion of hint bar |\n| `PomodoroHintLabel` | overlay fg | Label portion of hint bar |\n| `PomorodoDivider` | surface fg | `─` divider lines |\n\nExample override:\n\n```lua\nvim.api.nvim_set_hl(0, \"PomodoroClockPulse\", { fg = \"#ffffff\", bold = true })\n```\n\n---\n\n## 📋 Requirements\n\n- Neovim **0.9+**\n- A terminal with **Unicode / Nerd Font** support for block characters (`█ ▀ ▄ ▪`)\n\n---\n\n## 📄 License\n\nMIT © [lambertse](https://github.com/lambertse)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambertse%2Fnvim-pomodoro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flambertse%2Fnvim-pomodoro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambertse%2Fnvim-pomodoro/lists"}