vibe-pomo 0.2.1 → 0.2.2

package/README.md

@@ -27,6 +27,8 @@ 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.
+
 ```bash
 npm i -g vibe-pomo
 pomodoro install
@@ -71,6 +73,8 @@ pomodoro daemon
 
 ### 2. Start a session
 
+For the intended covered-screen workflow, open Claude Code inside a `tmux` session before running `/pomodoro ...`.
+
 ```bash
 # From Claude Code (recommended)
 /pomodoro 25m Refactor the auth module
@@ -80,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 falls back to a separate timer terminal.
+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.
 
 ```
 🍅 Pomodoro
@@ -163,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"` / `"tmux-window"` / name | Timer surface. `"tmux"` opens a popup overlay, `"tmux-window"` uses a new tmux window, and `"auto"` prefers the popup when `$TMUX` is set. |
+| `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. |
 | `soundOnOvertime` | bool | Play a sound when the timer hits zero |
 
 ---

package/README.zh.md

@@ -84,6 +84,8 @@ What did you do during this session?
 
 **前置条件：** Node.js 20+、Claude Code CLI
 
+**推荐条件：** 请在 `tmux` 里运行 Claude Code。这是 vibe-pomo 当前主推的交互方式：番茄钟会通过 `tmux popup` 覆盖当前 pane。非 `tmux` 环境下，会话仍然会正常运行，但计时器 UI 会退化为无界面模式。
+
 ```bash
 npm install -g vibe-pomo
 pomodoro install
@@ -111,6 +113,8 @@ pomodoro daemon
 
 ### 2. 开始一个会话
 
+如果你希望获得“盖住当前 Claude Code 窗口”的预期体验，请先在 `tmux` session 里打开 Claude Code，再执行 `/pomodoro ...`。
+
 ```bash
 # 在 Claude Code 中（推荐）
 /pomodoro 25m Refactor the auth module
@@ -120,7 +124,7 @@ pomodoro start 25m Refactor the auth module
 pomodoro start Refactor the auth module    # 使用默认时长
 ```
 
-如果 Claude Code 跑在 `tmux` 里，vibe-pomo 会在当前 pane 上弹出一个覆盖式 popup，把正在进行的任务界面盖住，直到你结束或中断番茄钟。非 `tmux` 环境下则回退到单独的计时器终端窗口。
+如果 Claude Code 跑在 `tmux` 里，vibe-pomo 会在当前 pane 上弹出一个覆盖式 popup，把正在进行的任务界面盖住，直到你结束或中断番茄钟。非 `tmux` 环境下则保持无界面模式：会话照常运行，但只通过 daemon 仪表板和统计视图展示，不再额外弹出终端窗口。
 
 ### 3. 会话进行中
 
@@ -177,7 +181,7 @@ Recent Sessions
 |------|------|------|
 | `defaultDurationMs` | 毫秒数 | 默认会话时长（25 分钟 = `1500000`） |
 | `decisionStrategy` | `"wait"` / `"break"` | 代理被阻塞时的策略：静默等待直到你结束会话（默认），或立即结束 |
-| `terminalEmulator` | `"auto"` / `"tmux"` / `"tmux-window"` / 名称 | 计时器展示方式。`"tmux"` 打开覆盖式 popup，`"tmux-window"` 使用新的 tmux window，`"auto"` 在检测到 `$TMUX` 时优先使用 popup |
+| `terminalEmulator` | `"auto"` / `"tmux"` / `"none"` | 计时器展示方式。`"tmux"` 打开覆盖式 popup，`"none"` 强制无界面模式，`"auto"` 仅在检测到 `$TMUX` 时使用 popup |
 | `soundOnOvertime` | 布尔值 | 计时归零时播放提示音 |
 
 ---

package/bin/pomodoro.mjs

@@ -109,20 +109,16 @@ async function cmdStart(args) {
     spawnWatcher(resp.sessionId)
   }
 
-  // Launch timer TUI in a new terminal window
+  // Only launch an interactive timer UI when we can safely cover the current
+  // Claude Code pane with a tmux popup. Otherwise stay headless and let the
+  // daemon/dashboard own visualization so the conversation flow is not disturbed.
   const timerEntry = join(ROOT, 'src', 'tui', 'timer', 'index.tsx')
-  const launched = await launchTerminal({
+  await launchTerminal({
     tsx: TSX,
     entryFile: timerEntry,
     sessionId: resp.sessionId,
     termPref: config.terminalEmulator,
   })
-
-  if (!launched) {
-    console.log(`POMODORO_TIMER_NOT_LAUNCHED`)
-    console.log(`  To watch the timer: node ${TSX} ${timerEntry} ${resp.sessionId}`)
-    console.log(`  To end the session: node ${join(ROOT, 'bin', 'pomodoro.mjs')} stop`)
-  }
 }
 
 async function cmdStop(args) {
@@ -187,52 +183,23 @@ async function cmdStopDaemon() {
 // ── Terminal launch helpers ───────────────────────────────────────────────────
 
 async function launchTerminal({ tsx, entryFile, sessionId, termPref }) {
-  const terminals = termPref && termPref !== 'auto'
-    ? [termPref]
-    : detectTerminals()
-
-  for (const term of terminals) {
-    const ok = await trySpawn(term, tsx, entryFile, sessionId)
-    if (ok) return true
-  }
-  return false
+  const mode = resolveTimerMode(termPref)
+  if (mode !== 'tmux-popup') return false
+  return trySpawn(mode, tsx, entryFile, sessionId)
 }
 
-function detectTerminals() {
-  const list = []
-  if (isWin) {
-    list.push('wt', 'cmd')
-    return list
+function resolveTimerMode(termPref) {
+  const pref = termPref ?? 'auto'
+  if (pref === 'none' || pref === 'headless') return 'none'
+  if ((pref === 'auto' || pref === 'tmux' || pref === 'tmux-popup') && process.env.TMUX) {
+    return 'tmux-popup'
   }
-  // Prefer a modal overlay when Claude Code is running inside tmux.
-  if (process.env.TMUX)                       list.push('tmux-popup')
-  if (process.env.STY)                        list.push('screen')
-  if (process.env.KITTY_WINDOW_ID)            list.push('kitty')
-  if (process.env.TERM_PROGRAM === 'WezTerm') list.push('wezterm')
-  list.push('tmux-window', 'gnome-terminal', 'xfce4-terminal', 'konsole', 'xterm', 'alacritty', 'wezterm', 'kitty')
-  return list
+  return 'none'
 }
 
 function buildCmd(term, tsx, entryFile, sessionId) {
-  // Quote paths for Windows (handles spaces in paths like AppData\Roaming\npm\...)
-  const q = isWin ? (p) => `"${p}"` : (p) => p
-  const inner = isWin
-    ? `${q(tsx)} ${q(entryFile)} ${sessionId}`
-    : `${tsx} ${entryFile} ${sessionId}`
   switch (term) {
-    case 'wt':             return ['wt', 'new-tab', '--', 'cmd.exe', '/k', inner]
-    case 'cmd':            return ['cmd.exe', '/c', `start cmd.exe /k "${inner}"`]
-    case 'tmux':
     case 'tmux-popup':     return buildTmuxPopupCmd(tsx, entryFile, sessionId)
-    case 'tmux-window':    return ['tmux', 'new-window', inner]
-    case 'screen':         return ['screen', '-X', 'screen', 'bash', '-c', inner]
-    case 'gnome-terminal': return ['gnome-terminal', '--', 'bash', '-c', inner]
-    case 'xfce4-terminal': return ['xfce4-terminal', '-e', inner]
-    case 'konsole':        return ['konsole', '-e', inner]
-    case 'xterm':          return ['xterm', '-e', inner]
-    case 'alacritty':      return ['alacritty', '-e', 'bash', '-c', inner]
-    case 'wezterm':        return ['wezterm', 'start', '--', 'bash', '-c', inner]
-    case 'kitty':          return ['kitty', 'bash', '-c', inner]
     default:               return null
   }
 }
@@ -279,8 +246,11 @@ function buildTmuxPopupCmd(tsx, entryFile, sessionId) {
     'tmux',
     'display-popup',
     '-E',
-    '-w', '90%',
-    '-h', '90%',
+    '-w', '100%',
+    '-h', '100%',
+    '-x', '0',
+    '-y', '0',
+    '-B',
     '-T', 'Pomodoro',
     `bash -lc ${shellQuote(timerCmd)}`,
   ]

package/install.mjs

@@ -109,23 +109,7 @@ argument-hint: "[duration e.g. 25m] [task description]"
 node ${pomodoroPath} start $ARGUMENTS
 \`\`\`
 
-## Step 2: Check if timer window launched
-
-Read the output from Step 1 carefully.
-
-If the output contains **\`POMODORO_TIMER_NOT_LAUNCHED\`**, the system could not open a separate timer window (common in SSH, VSCode, or headless environments). In this case you MUST tell the user BEFORE doing any work:
-
-> ⚠️ **No timer window could be opened automatically.**
->
-> Run one of these in another terminal to control your Pomodoro:
-> - **Watch timer:** (the command shown on the "To watch" line above)
-> - **End session:** (the command shown on the "To end" line above)
->
-> I'll now work on your task. The session will stay active until you run the stop command.
-
-After telling the user that once, continue immediately. Do not wait for a reply.
-
-## Step 3: Work autonomously during the focus session
+## Step 2: Work autonomously during the focus session
 
 The user has started a Pomodoro focus session and **will not be checking the screen** until the timer ends. Do not interrupt them.
 
@@ -136,6 +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
 - 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.1",
+  "version": "0.2.2",
   "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": {