vibe-pomo 0.2.2 → 0.2.3

package/README.md

@@ -27,7 +27,7 @@ Every session is logged — what the agent did, what you did — giving you a cl
 
 **Prerequisites:** Node.js 20+, Claude Code CLI
 
-**Recommended:** run Claude Code inside `tmux`. That is the primary supported interactive timer experience: vibe-pomo uses a `tmux` popup to cover the current pane during a Pomodoro. Outside `tmux`, sessions still run, but timer UI falls back to headless mode.
+**Recommended:** run Claude Code inside `tmux`. That is the primary supported interactive timer experience: vibe-pomo uses a `tmux` popup to cover the current pane during a Pomodoro. kitty can also support an overlay-style timer; terminals that cannot provide a comparable cover effect fall back to headless mode.
 
 ```bash
 npm i -g vibe-pomo
@@ -84,7 +84,7 @@ pomodoro start 25m Refactor the auth module
 pomodoro start Refactor the auth module    # uses default duration
 ```
 
-If Claude Code is running inside `tmux`, vibe-pomo opens a popup over the current pane so the ongoing task stays covered until you end or break the session. Outside `tmux`, it stays headless: the session still runs, but visualization remains in the daemon dashboard and stats view instead of opening another terminal window.
+If Claude Code is running inside `tmux`, vibe-pomo opens a popup over the current pane so the ongoing task stays covered until you end or break the session. In kitty, it will try to use an overlay window for the same purpose. Terminals that cannot provide a comparable cover effect stay headless: the session still runs, but visualization remains in the daemon dashboard and stats view instead of opening another terminal window.
 
 ```
 🍅 Pomodoro
@@ -167,7 +167,7 @@ Recent Sessions
 |--------|--------|-------------|
 | `defaultDurationMs` | ms | Default session duration (25 min = `1500000`) |
 | `decisionStrategy` | `"wait"` / `"break"` | When the agent is blocked: wait silently until you end the session (default), or end immediately |
-| `terminalEmulator` | `"auto"` / `"tmux"` / `"none"` | Timer surface. `"tmux"` opens a popup overlay, `"none"` forces headless mode, and `"auto"` uses the popup only when `$TMUX` is set. |
+| `terminalEmulator` | `"auto"` / `"tmux"` / `"kitty"` / `"none"` | Timer surface. `"tmux"` opens a popup overlay, `"kitty"` tries a kitty overlay window, `"none"` forces headless mode, and `"auto"` prefers supported cover-style overlays before falling back to headless mode. |
 | `soundOnOvertime` | bool | Play a sound when the timer hits zero |
 
 ---

package/README.zh.md

@@ -84,7 +84,7 @@ What did you do during this session?
 
 **前置条件：** Node.js 20+、Claude Code CLI
 
-**推荐条件：** 请在 `tmux` 里运行 Claude Code。这是 vibe-pomo 当前主推的交互方式：番茄钟会通过 `tmux popup` 覆盖当前 pane。非 `tmux` 环境下，会话仍然会正常运行，但计时器 UI 会退化为无界面模式。
+**推荐条件：** 请在 `tmux` 里运行 Claude Code。这是 vibe-pomo 当前主推的交互方式：番茄钟会通过 `tmux popup` 覆盖当前 pane。kitty 也可能支持类似的覆盖式计时器；其他无法提供同等级遮罩效果的终端会自动退化为无界面模式。
 
 ```bash
 npm install -g vibe-pomo
@@ -124,7 +124,7 @@ pomodoro start 25m Refactor the auth module
 pomodoro start Refactor the auth module    # 使用默认时长
 ```
 
-如果 Claude Code 跑在 `tmux` 里，vibe-pomo 会在当前 pane 上弹出一个覆盖式 popup，把正在进行的任务界面盖住，直到你结束或中断番茄钟。非 `tmux` 环境下则保持无界面模式：会话照常运行，但只通过 daemon 仪表板和统计视图展示，不再额外弹出终端窗口。
+如果 Claude Code 跑在 `tmux` 里，vibe-pomo 会在当前 pane 上弹出一个覆盖式 popup，把正在进行的任务界面盖住，直到你结束或中断番茄钟。在 kitty 里，它会尝试使用 overlay 窗口实现同样的遮罩效果。其他无法提供类似覆盖体验的终端则保持无界面模式：会话照常运行，但只通过 daemon 仪表板和统计视图展示，不再额外弹出终端窗口。
 
 ### 3. 会话进行中
 
@@ -181,7 +181,7 @@ Recent Sessions
 |------|------|------|
 | `defaultDurationMs` | 毫秒数 | 默认会话时长（25 分钟 = `1500000`） |
 | `decisionStrategy` | `"wait"` / `"break"` | 代理被阻塞时的策略：静默等待直到你结束会话（默认），或立即结束 |
-| `terminalEmulator` | `"auto"` / `"tmux"` / `"none"` | 计时器展示方式。`"tmux"` 打开覆盖式 popup，`"none"` 强制无界面模式，`"auto"` 仅在检测到 `$TMUX` 时使用 popup |
+| `terminalEmulator` | `"auto"` / `"tmux"` / `"kitty"` / `"none"` | 计时器展示方式。`"tmux"` 打开覆盖式 popup，`"kitty"` 尝试使用 kitty overlay，`"none"` 强制无界面模式，`"auto"` 会优先尝试支持遮罩效果的终端，否则退化为无界面模式 |
 | `soundOnOvertime` | 布尔值 | 计时归零时播放提示音 |
 
 ---

package/bin/pomodoro.mjs

@@ -184,7 +184,7 @@ async function cmdStopDaemon() {
 
 async function launchTerminal({ tsx, entryFile, sessionId, termPref }) {
   const mode = resolveTimerMode(termPref)
-  if (mode !== 'tmux-popup') return false
+  if (mode === 'none') return false
   return trySpawn(mode, tsx, entryFile, sessionId)
 }
 
@@ -194,12 +194,16 @@ function resolveTimerMode(termPref) {
   if ((pref === 'auto' || pref === 'tmux' || pref === 'tmux-popup') && process.env.TMUX) {
     return 'tmux-popup'
   }
+  if ((pref === 'auto' || pref === 'kitty' || pref === 'kitty-overlay') && process.env.KITTY_WINDOW_ID) {
+    return 'kitty-overlay'
+  }
   return 'none'
 }
 
 function buildCmd(term, tsx, entryFile, sessionId) {
   switch (term) {
     case 'tmux-popup':     return buildTmuxPopupCmd(tsx, entryFile, sessionId)
+    case 'kitty-overlay':  return buildKittyOverlayCmd(tsx, entryFile, sessionId)
     default:               return null
   }
 }
@@ -256,6 +260,22 @@ function buildTmuxPopupCmd(tsx, entryFile, sessionId) {
   ]
 }
 
+function buildKittyOverlayCmd(tsx, entryFile, sessionId) {
+  return [
+    'kitty',
+    '@',
+    'launch',
+    '--type=overlay-main',
+    '--cwd=current',
+    '--title=Pomodoro',
+    '--env=POMODORO_MODAL=1',
+    process.execPath,
+    tsx,
+    entryFile,
+    sessionId,
+  ]
+}
+
 function shellQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`
 }

package/install.mjs

@@ -120,7 +120,7 @@ The user has started a Pomodoro focus session and **will not be checking the scr
 - Focus only on what is **unambiguously clear** from the task description
 - If you encounter something that requires a user decision, **stop and record it** in \`.claude/pomodoro-pending.md\` — do NOT make assumptions or proceed on the user's behalf
 - Do not send notifications or ask questions — the user is in focus mode
-- If a timer UI is available, it may appear as a tmux popup. If not, continue headlessly — do not mention missing timer UI to the user unless they ask
+- If a timer UI is available, it may appear as a tmux popup or a kitty overlay. If not, continue headlessly — do not mention missing timer UI to the user unless they ask
 - When you have done all you can, write a summary to \`.claude/pomodoro-summary.md\`
 - Then wait quietly — the Pomodoro hook will manage the session lifecycle
 `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-pomo",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "You and your agent, both in flow. A Pomodoro timer for Claude Code that keeps agents working autonomously while you stay deep in focus — uninterrupted.",
   "type": "module",
   "bin": {