vibe-pomo 0.2.0 → 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
 ```
 
-A timer window opens in a new terminal. The agent starts working. You're free.
+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"` / name | Terminal for the timer window. Auto-detects from `$TERM_PROGRAM`, `$KITTY_WINDOW_ID`, etc. |
+| `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` 环境下则保持无界面模式：会话照常运行，但只通过 daemon 仪表板和统计视图展示，不再额外弹出终端窗口。
 
 ### 3. 会话进行中
 
@@ -177,7 +181,7 @@ Recent Sessions
 |------|------|------|
 | `defaultDurationMs` | 毫秒数 | 默认会话时长（25 分钟 = `1500000`） |
 | `decisionStrategy` | `"wait"` / `"break"` | 代理被阻塞时的策略：静默等待直到你结束会话（默认），或立即结束 |
-| `terminalEmulator` | `"auto"` / 名称 | 计时器窗口使用的终端。从 `$TERM_PROGRAM`、`$KITTY_WINDOW_ID` 等自动检测 |
+| `terminalEmulator` | `"auto"` / `"tmux"` / `"none"` | 计时器展示方式。`"tmux"` 打开覆盖式 popup，`"none"` 强制无界面模式，`"auto"` 仅在检测到 `$TMUX` 时使用 popup |
 | `soundOnOvertime` | 布尔值 | 计时归零时播放提示音 |
 
 ---

package/bin/pomodoro.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawn } from 'node:child_process'
+import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 import { readLock, removeLock } from '../src/shared/lockfile.mjs'
@@ -108,14 +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(TSX, timerEntry, resp.sessionId, config.terminalEmulator)
-
-  if (!launched) {
-    console.log(`\nOpen the timer in a new terminal:`)
-    console.log(`  tsx ${timerEntry} ${resp.sessionId}`)
-  }
+  await launchTerminal({
+    tsx: TSX,
+    entryFile: timerEntry,
+    sessionId: resp.sessionId,
+    termPref: config.terminalEmulator,
+  })
 }
 
 async function cmdStop(args) {
@@ -179,46 +182,24 @@ 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
+async function launchTerminal({ tsx, entryFile, sessionId, termPref }) {
+  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'
   }
-  if (process.env.KITTY_WINDOW_ID)        list.push('kitty')
-  if (process.env.TERM_PROGRAM === 'WezTerm') list.push('wezterm')
-  list.push('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 '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]
+    case 'tmux-popup':     return buildTmuxPopupCmd(tsx, entryFile, sessionId)
     default:               return null
   }
 }
@@ -244,8 +225,7 @@ function isInsideClaudeCode() {
 
 function spawnWatcher(sessionId) {
   const watcherPath = join(ROOT, 'src', 'watcher.mjs')
-  // Watch the grandparent process (Claude Code's Node.js process)
-  const watchPid = process.ppid
+  const watchPid = getWatchPid()
   const child = spawn(process.execPath, [watcherPath, String(watchPid), sessionId], {
     detached: true,
     stdio: 'ignore',
@@ -253,6 +233,48 @@ function spawnWatcher(sessionId) {
   child.unref()
 }
 
+function buildTmuxPopupCmd(tsx, entryFile, sessionId) {
+  const timerCmd = [
+    'POMODORO_MODAL=1',
+    shellQuote(process.execPath),
+    shellQuote(tsx),
+    shellQuote(entryFile),
+    shellQuote(sessionId),
+  ].join(' ')
+
+  return [
+    'tmux',
+    'display-popup',
+    '-E',
+    '-w', '100%',
+    '-h', '100%',
+    '-x', '0',
+    '-y', '0',
+    '-B',
+    '-T', 'Pomodoro',
+    `bash -lc ${shellQuote(timerCmd)}`,
+  ]
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+function getWatchPid() {
+  if (isWin) return process.ppid
+
+  try {
+    const out = execFileSync('ps', ['-o', 'ppid=', '-p', String(process.ppid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+    const ppid = Number.parseInt(out, 10)
+    if (Number.isInteger(ppid) && ppid > 1) return ppid
+  } catch {}
+
+  return process.ppid
+}
+
 function formatMs(ms) {
   const m = Math.floor(ms / 60000)
   const s = Math.floor((ms % 60000) / 1000)

package/install.mjs

@@ -113,11 +113,14 @@ node ${pomodoroPath} start $ARGUMENTS
 
 The user has started a Pomodoro focus session and **will not be checking the screen** until the timer ends. Do not interrupt them.
 
+**Current project**: Check \`\$CLAUDE_PROJECT_DIR\` or run \`pwd\` — work only on files in that directory. Do not reference or modify any other project.
+
 **Task**: $ARGUMENTS
 
 - 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.0",
+  "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": {

package/src/daemon/index.mjs

@@ -21,6 +21,8 @@ const sessions = new Map()
 
 /** sessionId → DB row id */
 const dbIds = new Map()
+/** sessionId → DB row id for sessions that already ended but may still receive user activity */
+const finishedDbIds = new Map()
 
 // ── IPC Handlers ─────────────────────────────────────────────────────────────
 
@@ -78,9 +80,10 @@ ipc.on(MSG.SESSION_BREAK, (msg) => {
 })
 
 ipc.on(MSG.SESSION_UPDATE_ACTIVITY, (msg) => {
-  const dbId = dbIds.get(msg.sessionId)
+  const dbId = dbIds.get(msg.sessionId) ?? finishedDbIds.get(msg.sessionId)
   if (!dbId) return { error: 'session not found' }
   updateSessionActivity(dbId, { userActivity: msg.userActivity })
+  finishedDbIds.delete(msg.sessionId)
   return { ok: true }
 })
 
@@ -163,6 +166,10 @@ function wireSessionEvents(session) {
     }
 
     sessions.delete(sessionId)
+    if (dbId) {
+      finishedDbIds.set(sessionId, dbId)
+      setTimeout(() => finishedDbIds.delete(sessionId), 30 * 60 * 1000).unref()
+    }
     dbIds.delete(sessionId)
 
     ipc.broadcast({ type: EVT.SESSION_ENDED, sessionId, status, actualMs })

package/src/daemon/ipc.mjs

@@ -62,7 +62,7 @@ export class IpcServer {
           const handler = this.#handlers['query']
           if (handler) {
             const state = await handler(msg, socket)
-            if (state) socket.write(encode({ type: EVT.STATE, ...state }))
+            if (state) socket.write(encode({ type: EVT.SNAPSHOT, ...state }))
           }
           continue
         }

package/src/daemon/session.mjs

@@ -58,6 +58,7 @@ export class Session extends EventEmitter {
     return {
       sessionId: this.id,
       projectDir: this.projectDir,
+      projectHash: this.projectHash,
       task: this.task,
       plannedMs: this.plannedMs,
       state: this.#state,

package/src/hooks/notification.mjs

@@ -1,9 +1,10 @@
 /**
  * Notification hook — queue notifications during an active Pomodoro session.
  */
-import { readLock, projectHash } from '../shared/lockfile.mjs'
+import { readLock } from '../shared/lockfile.mjs'
 import { sendAndReceive } from '../shared/ipcClient.mjs'
-import { STATE, MSG } from '../shared/protocol.mjs'
+import { MSG } from '../shared/protocol.mjs'
+import { findActiveSession } from '../shared/findActiveSession.mjs'
 
 async function readStdin() {
   return new Promise((resolve) => {
@@ -20,8 +21,6 @@ async function main() {
   if (!lock) process.exit(0)
 
   const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
-  const hash = projectHash(projectDir)
-
   let state
   try {
     state = await sendAndReceive({ type: MSG.QUERY })
@@ -29,10 +28,7 @@ async function main() {
     process.exit(0)
   }
 
-  const active = state.sessions?.find(
-    (s) => s.projectHash === hash &&
-           (s.state === STATE.RUNNING || s.state === STATE.OVERTIME)
-  )
+  const active = findActiveSession(state.sessions, projectDir)
   if (!active) process.exit(0)
 
   const raw = await readStdin()

package/src/hooks/preToolUse.mjs

@@ -2,9 +2,10 @@
  * PreToolUse hook — auto-approve tool calls during an active Pomodoro session.
  * Transparency: if no daemon running or no active session for this project, exits 0.
  */
-import { readLock, projectHash } from '../shared/lockfile.mjs'
+import { readLock } from '../shared/lockfile.mjs'
 import { sendAndReceive } from '../shared/ipcClient.mjs'
-import { STATE, MSG } from '../shared/protocol.mjs'
+import { MSG } from '../shared/protocol.mjs'
+import { findActiveSession } from '../shared/findActiveSession.mjs'
 
 async function main() {
   const lock = readLock()
@@ -19,12 +20,7 @@ async function main() {
     process.exit(0)
   }
 
-  // Find an active session for this project
-  const hash = projectHash(projectDir)
-  const active = state.sessions?.find(
-    (s) => s.projectHash === hash &&
-           (s.state === STATE.RUNNING || s.state === STATE.OVERTIME)
-  )
+  const active = findActiveSession(state.sessions, projectDir)
 
   if (active) {
     process.stdout.write(JSON.stringify({

package/src/hooks/stop.mjs

@@ -2,9 +2,10 @@
  * Stop hook — called when Claude Code agent finishes.
  * Blocks the agent if a Pomodoro is active for this project.
  */
-import { readLock, projectHash } from '../shared/lockfile.mjs'
+import { readLock } from '../shared/lockfile.mjs'
 import { sendAndReceive } from '../shared/ipcClient.mjs'
-import { STATE, MSG } from '../shared/protocol.mjs'
+import { MSG } from '../shared/protocol.mjs'
+import { findActiveSession } from '../shared/findActiveSession.mjs'
 
 async function readStdin() {
   return new Promise((resolve) => {
@@ -21,8 +22,6 @@ async function main() {
   if (!lock) process.exit(0)
 
   const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
-  const hash = projectHash(projectDir)
-
   let state
   try {
     state = await sendAndReceive({ type: MSG.QUERY })
@@ -30,10 +29,7 @@ async function main() {
     process.exit(0)
   }
 
-  const active = state.sessions?.find(
-    (s) => s.projectHash === hash &&
-           (s.state === STATE.RUNNING || s.state === STATE.OVERTIME)
-  )
+  const active = findActiveSession(state.sessions, projectDir)
   if (!active) process.exit(0)
 
   const raw = await readStdin()
@@ -60,6 +56,7 @@ async function main() {
         `Time remaining: ${resp.remainingFormatted}.`,
         'The user is not available. Do not send messages or notifications.',
         'Record any pending decisions in `.claude/pomodoro-pending.md` and wait quietly.',
+        'If the user asks how to end the session, tell them to run: pomodoro stop',
       ].join(' '),
     }) + '\n')
   }

package/src/shared/findActiveSession.mjs

@@ -0,0 +1,27 @@
+import { resolve } from 'node:path'
+import { projectHash } from './lockfile.mjs'
+import { STATE } from './protocol.mjs'
+
+function normalizeProjectDir(projectDir) {
+  return resolve(projectDir ?? process.cwd())
+}
+
+function isActiveSession(session) {
+  return session?.state === STATE.RUNNING || session?.state === STATE.OVERTIME
+}
+
+/**
+ * Match the current Claude project to the daemon's active session.
+ * Prefer the stable hash, but fall back to normalized projectDir for
+ * compatibility with older snapshots that did not include projectHash.
+ */
+export function findActiveSession(sessions, projectDir) {
+  const normalizedDir = normalizeProjectDir(projectDir)
+  const hash = projectHash(normalizedDir)
+
+  return sessions?.find((session) => {
+    if (!isActiveSession(session)) return false
+    if (session.projectHash === hash) return true
+    return normalizeProjectDir(session.projectDir) === normalizedDir
+  }) ?? null
+}

package/src/tui/timer/TimerApp.tsx

@@ -34,6 +34,7 @@ export function TimerApp({
 }: TimerAppProps) {
   const { stdout } = useStdout()
   const width = stdout?.columns ?? 60
+  const isModal = process.env.POMODORO_MODAL === '1'
 
   const [timerState, setTimerState] = useState(initialState)
   const [remaining, setRemaining] = useState(initialRemaining)
@@ -97,13 +98,13 @@ export function TimerApp({
   useInput((input, key) => {
     if (phase === 'activity-input') return // TextInput handles keys in this phase
     if (phase === 'done') {
-      if (input === 'q' || key.escape) process.exit(0)
+      if (!isModal && (input === 'q' || key.escape)) process.exit(0)
       return
     }
     if (timerState === STATE.ENDED) return
     if (input === 'e' || input === 'E') sendEnd()
     if (input === 'b' || input === 'B') sendBreak()
-    if (input === 'q' || key.escape) process.exit(0)
+    if (!isModal && (input === 'q' || key.escape)) process.exit(0)
   })
 
   const isOvertime = timerState === STATE.OVERTIME
@@ -141,10 +142,10 @@ export function TimerApp({
 
   // ── Timer phase ───────────────────────────────────────────────────────────
   const keybindings = isEnded
-    ? '[Q] Quit'
+    ? (isModal ? 'Submit your notes to close the Pomodoro overlay' : '[Q] Quit')
     : isOvertime
-      ? '[E] End Session    [B] Break    [Q] Quit'
-      : '[B] Break    [Q] Quit'
+      ? (isModal ? '[E] End Session    [B] Break' : '[E] End Session    [B] Break    [Q] Quit')
+      : (isModal ? '[B] Break' : '[B] Break    [Q] Quit')
 
   return (
     <Box flexDirection="column" width={width} paddingX={2} paddingY={1}>
@@ -159,6 +160,12 @@ export function TimerApp({
       <Box marginTop={1}>
         <Text color="gray" dimColor>{keybindings}</Text>
       </Box>
+
+      {isModal && (
+        <Box marginTop={1}>
+          <Text color="gray" dimColor>The current Claude Code pane will stay covered until you end or break this Pomodoro.</Text>
+        </Box>
+      )}
     </Box>
   )
 }