vibe-pomo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 vibe-pomo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# vibe-pomo 🍅
+
+> You and your agent, both in flow.
+
+<!-- screenshot: dashboard terminal showing active sessions + project stats -->
+
+---
+
+## Why vibe-pomo
+
+Most AI coding tools are built around one assumption: you're always watching. Every tool call, every decision, every completion — the agent pings you, waits for you, interrupts you. Each exchange is small, but the cumulative cost is enormous: you never get more than a few minutes of unbroken attention.
+
+**vibe-pomo flips this.** Start a Pomodoro, hand the agent a task, and step away. The agent works autonomously — notifications silenced, decisions queued, no interruptions. When the timer ends, *you* decide when to come back. Not the agent.
+
+**Deep focus, on both sides.**
+Block out distraction-free time for yourself while the agent runs its own uninterrupted work session. No context switches. No reactive loops. Just two parallel flows converging when you're ready.
+
+**Know where your time goes.**
+Every session is logged with what the agent accomplished and what you worked on. Review per-project focus time, browse session history, and see exactly how your hours were spent — a clear record for personal retrospectives and project planning.
+
+---
+
+## How It Works
+
+Two terminals, two roles:
+
+```
+Terminal A — daemon (always open)       Terminal B — Claude Code conversation
+─────────────────────────────────       ───────────────────────────────────────
+$ pomodoro daemon                       /pomodoro 25m Fix auth bug
+                                                   |
+  🍅 Pomodoro  daemon running                      +---> Timer window opens
+                                                         Agent starts working
+  Active Sessions                                        Notifications silenced
+   23:41  my-project  Fix auth bug                       Tool calls auto-approved
+
+  Project Focus Time
+   my-project  ████████████░░  3h 45m
+
+  Recent Sessions
+   my-project  Fix auth bug
+    🤖 Rewrote JWT middleware
+    👤 Had a planning call
+```
+
+```
+Timer window (per session)
+──────────────────────────────────
+  🍅 Pomodoro
+
+        +02:13  OVERTIME
+
+  Task: Fix auth bug
+
+  Notifications
+  ┌──────────────────────────────┐
+  │ Build passed                 │
+  │ Tests: 42 passed             │
+  └──────────────────────────────┘
+
+  [E] End Session   [B] Break   [Q] Quit
+```
+
+When the timer ends, queued notifications are released and you're prompted to log what *you* did during that time:
+
+```
+What did you do during this session?
+(optional — press Enter to skip)
+
+> Reviewed the RFC, had a planning call with the team
+```
+
+This gets saved alongside the agent's summary, giving you a dual-perspective record of every session.
+
+---
+
+## Installation
+
+**Prerequisites:** Node.js 20+, Claude Code CLI
+
+```bash
+npm install -g vibe-pomo
+pomodoro install
+```
+
+`pomodoro install` registers three Claude Code hooks in `~/.claude/settings.json` and installs the `/pomodoro`, `/pomodoro-stats`, and `/pomodoro-stop` slash commands:
+
+- **PreToolUse** — auto-approves all tool calls during an active session
+- **Notification** — silently queues notifications until the timer ends
+- **Stop** — holds the agent in place until you end the session
+
+> All three hooks **exit immediately with no effect** when no Pomodoro is active. They won't interfere with any other Claude Code setup or slash command frameworks.
+
+---
+
+## Usage
+
+### 1. Start the daemon (once, keep this terminal open)
+
+```bash
+pomodoro daemon
+```
+
+Shows a live dashboard: active sessions with countdowns, per-project focus time, and recent session history.
+
+### 2. Start a session
+
+```bash
+# From Claude Code (recommended)
+/pomodoro 25m Refactor the auth module
+
+# From any terminal
+pomodoro start 25m Refactor the auth module
+pomodoro start Refactor the auth module    # uses default duration
+```
+
+A timer window opens. The agent starts working. You're free.
+
+### 3. During the session
+
+The agent works autonomously — tool calls approved, notifications queued, decisions logged. You can check in from Claude Code without exiting:
+
+```
+/pomodoro-stats    view time tracking statistics
+/pomodoro-stop     break the current session
+```
+
+### 4. When the timer ends
+
+Timer switches to overtime. Queued notifications appear. Press **E** to end, log what you did, then review the agent's summary and any pending decisions in `.claude/pomodoro-summary.md` and `.claude/pomodoro-pending.md`.
+
+### 5. Review your stats
+
+```bash
+pomodoro stats
+```
+
+```
+Project Focus Time
+──────────────────────────────────────────────────────────────────
+my-project      ████████████████░░░░░░░░░░░░░░    4h 20m
+side-project    ██████░░░░░░░░░░░░░░░░░░░░░░░░    1h 45m
+
+Recent Sessions
+──────────────────────────────────────────────────────────────────
+4/13  my-project   Refactor auth module      28m  completed
+  🤖  Rewrote JWT middleware, pending: refresh token expiry strategy
+  👤  Read RFC, had planning call with team
+
+4/13  my-project   Fix payment webhook       18m  completed
+  🤖  Found and fixed Stripe signature validation bug
+  👤  Coffee, cleared inbox
+```
+
+---
+
+## Configuration
+
+`~/.claude/pomodoro.json` is created on first run:
+
+```json
+{
+  "defaultDurationMs": 1500000,
+  "decisionStrategy": "wait",
+  "terminalEmulator": "auto",
+  "soundOnOvertime": true
+}
+```
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `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. |
+| `soundOnOvertime` | bool | Play a sound when the timer hits zero |
+
+---
+
+## Commands
+
+```
+pomodoro daemon                  Start daemon + live dashboard
+pomodoro start [dur] [task]      Start a session
+pomodoro stop                    Break the current session
+pomodoro stats                   Show time tracking statistics
+pomodoro install                 Register hooks with Claude Code
+pomodoro stop-daemon             Stop the global daemon
+```
+
+Duration formats: `25m`, `1h`, `90s`, or a plain number (treated as minutes).
+
+---
+
+## Compatibility
+
+vibe-pomo hooks activate only when the daemon is running. When no session is active, all three hooks exit immediately — no output, no side effects. One global daemon handles all your Claude Code projects simultaneously.
+
+---
+
+## License
+
+MIT

package/bin/pomodoro.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { readLock, removeLock } from '../src/shared/lockfile.mjs'
+import { sendAndReceive } from '../src/shared/ipcClient.mjs'
+import { loadConfig, parseDuration, ensureConfigFile } from '../src/shared/config.mjs'
+import { MSG, DECISION } from '../src/shared/protocol.mjs'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const ROOT = join(__dirname, '..')
+const TSX = join(ROOT, 'node_modules', '.bin', 'tsx')
+
+const [,, cmd, ...args] = process.argv
+
+const HELP = `Usage: pomodoro <command> [options]
+
+Commands:
+  daemon                           Start daemon + live dashboard (run this first)
+  start [duration] [task...]       Start a Pomodoro session
+  stop [sessionId]                 Break the current (or specified) session
+  stats                            Show time tracking statistics
+  install                          Register hooks in ~/.claude/settings.json
+  stop-daemon                      Stop the global daemon
+
+Examples:
+  pomodoro daemon                  (keep this terminal open)
+  pomodoro start 25m Fix login bug
+  pomodoro start Fix login bug     (uses default 25m)
+  pomodoro stop
+  pomodoro stats
+`
+
+const COMMANDS = {
+  daemon:        cmdDaemon,
+  start:         cmdStart,
+  stop:          cmdStop,
+  stats:         cmdStats,
+  stat:          cmdStats,    // alias
+  install:       cmdInstall,
+  'stop-daemon': cmdStopDaemon,
+}
+
+const handler = COMMANDS[cmd]
+if (!handler) {
+  process.stdout.write(HELP)
+  process.exit(cmd ? 1 : 0)
+}
+await handler(args)
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+async function cmdDaemon() {
+  // Launch dashboard TUI (which also starts the daemon in-process)
+  const dashboardEntry = join(ROOT, 'src', 'tui', 'dashboard', 'index.tsx')
+  const child = spawn(TSX, [dashboardEntry], { stdio: 'inherit' })
+  child.on('exit', (code) => process.exit(code ?? 0))
+}
+
+async function cmdStart(args) {
+  ensureConfigFile()
+  const config = loadConfig()
+
+  const lock = readLock()
+  if (!lock) {
+    console.error('Pomodoro daemon is not running.')
+    console.error('Start it first with: pomodoro daemon')
+    process.exit(1)
+  }
+
+  // Parse optional leading duration, rest is task
+  let durationMs = config.defaultDurationMs
+  let taskParts = [...args]
+
+  if (taskParts[0] && !taskParts[0].startsWith('-')) {
+    const parsed = parseDuration(taskParts[0])
+    if (parsed) { durationMs = parsed; taskParts.shift() }
+  }
+  const task = taskParts.join(' ')
+
+  const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
+
+  let resp
+  try {
+    resp = await sendAndReceive({
+      type: MSG.SESSION_CREATE,
+      projectDir,
+      task,
+      plannedMs: durationMs,
+      decisionStrategy: config.decisionStrategy,
+    })
+  } catch {
+    console.error('Could not reach daemon. Is `pomodoro daemon` running?')
+    process.exit(1)
+  }
+
+  if (resp.error) {
+    console.error('Error:', resp.error)
+    process.exit(1)
+  }
+
+  console.log(`Session started (${formatMs(durationMs)})`)
+  if (task) console.log(`Task: ${task}`)
+
+  // If running inside Claude Code, start a PPID watcher for auto-break on exit
+  if (isInsideClaudeCode()) {
+    spawnWatcher(resp.sessionId)
+  }
+
+  // Launch timer TUI in a new terminal window
+  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}`)
+  }
+}
+
+async function cmdStop(args) {
+  const lock = readLock()
+  if (!lock) { console.log('No daemon running.'); process.exit(0) }
+
+  // If sessionId given, stop that session; otherwise stop first active
+  let sessionId = args[0]
+  if (!sessionId) {
+    let state
+    try { state = await sendAndReceive({ type: MSG.QUERY }) } catch {
+      console.error('Daemon unreachable.')
+      process.exit(1)
+    }
+    const projectDir = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
+    const active = state.sessions?.find((s) => s.projectDir === projectDir)
+      ?? state.sessions?.[0]
+    if (!active) { console.log('No active sessions.'); process.exit(0) }
+    sessionId = active.sessionId
+  }
+
+  try {
+    await sendAndReceive({ type: MSG.SESSION_BREAK, sessionId })
+    console.log('Session broken.')
+  } catch {
+    console.error('Could not reach daemon.')
+  }
+}
+
+async function cmdStats() {
+  const lock = readLock()
+  if (!lock) {
+    // Show static stats from DB
+    const { printStats } = await import('../src/daemon/db.mjs')
+    printStats()
+    return
+  }
+  // Launch the dashboard in read-only mode (connect to existing daemon)
+  // For now, print stats — a full "attach to dashboard" is future work
+  const { printStats } = await import('../src/daemon/db.mjs')
+  printStats()
+}
+
+async function cmdInstall() {
+  const { runInstall } = await import('../install.mjs')
+  runInstall()
+}
+
+async function cmdStopDaemon() {
+  const lock = readLock()
+  if (!lock) { console.log('No daemon running.'); process.exit(0) }
+  try {
+    process.kill(lock.pid, 'SIGTERM')
+    removeLock()
+    console.log('Daemon stopped.')
+  } catch {
+    removeLock()
+    console.log('Daemon was already stopped; lock cleaned up.')
+  }
+}
+
+// ── 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
+}
+
+function detectTerminals() {
+  const list = []
+  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
+}
+
+function buildCmd(term, tsx, entryFile, sessionId) {
+  const inner = `${tsx} ${entryFile} ${sessionId}`
+  switch (term) {
+    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
+  }
+}
+
+function trySpawn(term, tsx, entryFile, sessionId) {
+  const cmd = buildCmd(term, tsx, entryFile, sessionId)
+  if (!cmd) return Promise.resolve(false)
+  return new Promise((resolve) => {
+    let done = false
+    try {
+      const child = spawn(cmd[0], cmd.slice(1), { detached: true, stdio: 'ignore' })
+      child.on('error', () => { if (!done) { done = true; resolve(false) } })
+      child.on('spawn', () => { if (!done) { done = true; child.unref(); resolve(true) } })
+      setTimeout(() => { if (!done) { done = true; child.unref(); resolve(true) } }, 300)
+    } catch { resolve(false) }
+  })
+}
+
+function isInsideClaudeCode() {
+  // Claude Code sets CLAUDE_PROJECT_DIR; also check for CLAUDE_CODE_ENTRYPOINT
+  return !!(process.env.CLAUDE_PROJECT_DIR || process.env.CLAUDE_CODE_ENTRYPOINT)
+}
+
+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 child = spawn(process.execPath, [watcherPath, String(watchPid), sessionId], {
+    detached: true,
+    stdio: 'ignore',
+  })
+  child.unref()
+}
+
+function formatMs(ms) {
+  const m = Math.floor(ms / 60000)
+  const s = Math.floor((ms % 60000) / 1000)
+  return s > 0 ? `${m}m ${s}s` : `${m}m`
+}

package/install.mjs

@@ -0,0 +1,170 @@
+/**
+ * install.mjs — Register Pomodoro hooks in ~/.claude/settings.json
+ *
+ * Run once: node install.mjs   or   pomodoro install
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createRequire } from 'node:module'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const HOOKS_DIR = join(__dirname, 'src', 'hooks')
+const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json')
+
+export function runInstall() {
+  const nodeExec = process.execPath
+
+  const hookDefs = {
+    PreToolUse: [
+      {
+        matcher: '.*',
+        hooks: [{
+          type: 'command',
+          command: `${nodeExec} ${join(HOOKS_DIR, 'preToolUse.mjs')}`,
+        }],
+      },
+    ],
+    Notification: [
+      {
+        hooks: [{
+          type: 'command',
+          command: `${nodeExec} ${join(HOOKS_DIR, 'notification.mjs')}`,
+        }],
+      },
+    ],
+    Stop: [
+      {
+        hooks: [{
+          type: 'command',
+          command: `${nodeExec} ${join(HOOKS_DIR, 'stop.mjs')}`,
+        }],
+      },
+    ],
+  }
+
+  // Read existing settings
+  let settings = {}
+  if (existsSync(SETTINGS_PATH)) {
+    try {
+      settings = JSON.parse(readFileSync(SETTINGS_PATH, 'utf8'))
+    } catch {
+      console.error(`Could not parse ${SETTINGS_PATH}. Aborting.`)
+      process.exit(1)
+    }
+  } else {
+    mkdirSync(dirname(SETTINGS_PATH), { recursive: true })
+  }
+
+  // Merge hooks — avoid duplicates by checking command paths
+  settings.hooks = settings.hooks ?? {}
+
+  let added = 0
+  for (const [event, defs] of Object.entries(hookDefs)) {
+    settings.hooks[event] = settings.hooks[event] ?? []
+    for (const def of defs) {
+      const commandToAdd = def.hooks[0].command
+      const alreadyRegistered = settings.hooks[event].some(
+        (existing) => existing.hooks?.some((h) => h.command === commandToAdd)
+      )
+      if (!alreadyRegistered) {
+        settings.hooks[event].push(def)
+        added++
+      }
+    }
+  }
+
+  writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n', 'utf8')
+
+  if (added > 0) {
+    console.log(`✓ Registered ${added} hook(s) in ${SETTINGS_PATH}`)
+  } else {
+    console.log(`Hooks already registered in ${SETTINGS_PATH}`)
+  }
+
+  // Also install project-local slash command
+  installSlashCommand()
+}
+
+function installSlashCommand() {
+  const globalCommandsDir = join(homedir(), '.claude', 'commands')
+  mkdirSync(globalCommandsDir, { recursive: true })
+
+  const commands = [
+    { file: 'pomodoro.md',       writer: writePomodoroCommand },
+    { file: 'pomodoro-stats.md', writer: writeStatsCommand },
+    { file: 'pomodoro-stop.md',  writer: writeStopCommand },
+  ]
+
+  for (const { file, writer } of commands) {
+    const dest = join(globalCommandsDir, file)
+    writer(dest)
+    console.log(`✓ Slash command: ~/.claude/commands/${file}`)
+  }
+}
+
+function writePomodoroCommand(dest) {
+  const pomodoroPath = join(__dirname, 'bin', 'pomodoro.mjs')
+  const nodeExec = process.execPath
+  writeFileSync(dest, `---
+description: Start a Pomodoro focus session — agent works autonomously until timer ends
+argument-hint: "[duration e.g. 25m] [task description]"
+---
+
+## Step 1: Start the Pomodoro timer
+
+\`\`\`bash
+${nodeExec} ${pomodoroPath} start $ARGUMENTS
+\`\`\`
+
+## 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.
+
+**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
+- 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
+`, 'utf8')
+}
+
+function writeStatsCommand(dest) {
+  const pomodoroPath = join(__dirname, 'bin', 'pomodoro.mjs')
+  const nodeExec = process.execPath
+  writeFileSync(dest, `---
+description: Show Pomodoro time tracking statistics
+---
+
+Run the following command and display the output to the user:
+
+\`\`\`bash
+${nodeExec} ${pomodoroPath} stats
+\`\`\`
+`, 'utf8')
+}
+
+function writeStopCommand(dest) {
+  const pomodoroPath = join(__dirname, 'bin', 'pomodoro.mjs')
+  const nodeExec = process.execPath
+  writeFileSync(dest, `---
+description: Break (stop) the current Pomodoro session
+---
+
+Run the following command to break the active Pomodoro session:
+
+\`\`\`bash
+${nodeExec} ${pomodoroPath} stop
+\`\`\`
+
+Then confirm to the user that the session has been stopped.
+`, 'utf8')
+}
+
+// Run directly if called as script
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  runInstall()
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "vibe-pomo",
+  "version": "0.1.0",
+  "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": {
+    "pomodoro": "bin/pomodoro.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "install.mjs",
+    "README.md"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "pomodoro",
+    "focus",
+    "productivity",
+    "ai",
+    "agent",
+    "tui"
+  ],
+  "license": "MIT",
+  "author": "Weilong Qin <qinweilong0813@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Weilong-Qin/vibe-pomo.git"
+  },
+  "scripts": {
+    "start": "node bin/pomodoro.mjs",
+    "tui": "tsx src/tui/index.tsx"
+  },
+  "dependencies": {
+    "better-sqlite3": "^9.4.3",
+    "ink": "^5.1.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.8",
+    "@types/react": "^18.3.1",
+    "tsx": "^4.19.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}