bestviber 0.1.0 → 0.2.0

package/README.md

@@ -2,12 +2,28 @@
 
 Focus timer and focus analytics for you and your AI agents.
 
+## Claude Code, in two commands
+
 ```sh
 npm install -g bestviber
-bestviber login          # approve a code in your browser
+bestviber login
+```
+
+`login` opens your browser to approve a short code, installs the agent skill,
+and asks whether to track your Claude Code sessions automatically. Say yes and
+there is nothing else to do: every Claude Code session is timed and filed
+under the repository you work in. Quiet stretches are recorded as pauses, and
+ten quiet minutes end the session. Then ask your agent "how was my week?", or
+run `bestviber week`.
+
+`bestviber logout` signs out and removes the tracking.
+
+## By hand
+
+```sh
 bestviber start          # start a focus session
 bestviber stop --note "wrote the launch post"
-bestviber week           # this week: total, by day, by hour, by tag, vs last week
+bestviber week           # this week: total, by day, by hour, by tag and project
 bestviber insights       # peak hours, best weekday, streaks, trends
 ```
 
@@ -15,11 +31,13 @@ Every command takes `--json` for scripts and agents. `bestviber tools` lists
 every action the server offers and `bestviber run <action>` runs any of them,
 so new features work without updating the CLI.
 
-## Agents
+## Other agents
 
-- `bestviber skill install` adds the bestviber skill for Claude Code and
-  other agents that read `~/.agents/skills`.
+- The skill goes to `~/.claude/skills/bestviber`, and also to
+  `~/.agents/skills/bestviber` if you have an `~/.agents` folder. Reinstall or
+  update it with `bestviber skill install`.
 - `bestviber mcp` prints how to connect any MCP client to
-  `https://www.bestviber.com/api/mcp`.
+  `https://www.bestviber.com/api/mcp`. Sign in first: the setup line uses
+  your token.
 
 Free. Same account as [bestviber.com](https://www.bestviber.com).

package/bin/bestviber.mjs

@@ -10,9 +10,9 @@ const pkg = JSON.parse(
 
 function help() {
   const width = Math.max(...Object.keys(commands).map((c) => c.length))
-  const lines = Object.entries(commands).map(
-    ([name, c]) => `  ${name.padEnd(width)}  ${c.summary}`,
-  )
+  const lines = Object.entries(commands)
+    .filter(([, c]) => !c.hidden)
+    .map(([name, c]) => `  ${name.padEnd(width)}  ${c.summary}`)
   return `bestviber ${pkg.version}: focus timer and focus analytics for you and your agents
 
 Usage: bestviber <command> [options]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bestviber",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Focus timer and focus analytics for you and your AI agents. Start, pause and finish sessions, and get daily, weekly and monthly stats from the terminal.",
   "keywords": [
     "focus",

package/src/commands.mjs

@@ -18,6 +18,15 @@ import {
   writeConfig,
 } from './client.mjs'
 import { clock, duration, elapsed, stats } from './format.mjs'
+import {
+  clearTrackingState,
+  hasClaudeCode,
+  hooksInstalled,
+  installHooks,
+  launchHook,
+  runHookWorker,
+  uninstallHooks,
+} from './hooks.mjs'
 
 /**
  * @typedef {{ flags: Record<string, any>, args: string[], json: boolean }} Ctx
@@ -25,10 +34,80 @@ import { clock, duration, elapsed, stats } from './format.mjs'
  *   summary: string,
  *   usage?: string,
  *   actions: string[],
+ *   hidden?: boolean,
  *   run: (ctx: Ctx) => Promise<unknown>,
  * }} Command
  */
 
+/** Download the agent skill into the folders agents read. */
+async function installSkill(/** @type {string | undefined} */ dir) {
+  // ~/.claude/skills for Claude Code; ~/.agents/skills is the shared folder
+  // other agents read, when it exists.
+  const dirs = dir
+    ? [dir]
+    : [
+        join(homedir(), '.claude', 'skills'),
+        ...(existsSync(join(homedir(), '.agents'))
+          ? [join(homedir(), '.agents', 'skills')]
+          : []),
+      ]
+  const files = await Promise.all(
+    ['SKILL.md', 'reference.md'].map(async (name) => {
+      const res = await fetch(`${await baseUrl()}/skill/${name}`)
+      if (!res.ok)
+        throw new CliError(`Could not download ${name} (HTTP ${res.status}).`)
+      return { name, body: await res.text() }
+    }),
+  )
+  const written = []
+  for (const d of dirs) {
+    const target = join(d, 'bestviber')
+    await mkdir(target, { recursive: true })
+    for (const f of files) await writeFile(join(target, f.name), f.body)
+    written.push(target)
+  }
+  return written
+}
+
+/** Yes/no on a terminal; with no terminal (an agent ran us), the default. */
+async function confirm(/** @type {string} */ question, fallback = true) {
+  if (!process.stdin.isTTY || !process.stderr.isTTY) return fallback
+  const { createInterface } = await import('node:readline/promises')
+  const rl = createInterface({ input: process.stdin, output: process.stderr })
+  const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase()
+  rl.close()
+  return answer === '' ? fallback : answer.startsWith('y')
+}
+
+/** After sign-in: the skill, and automatic tracking for Claude Code. */
+async function setUpAgents() {
+  const lines = []
+  try {
+    await installSkill(undefined)
+    lines.push('Installed the agent skill.')
+  } catch (err) {
+    lines.push(`Skipped the agent skill: ${/** @type {Error} */ (err).message}`)
+  }
+  if (!hasClaudeCode()) return lines
+  const ask = process.stdin.isTTY && process.stderr.isTTY
+  if (
+    await confirm(
+      '\nTrack your Claude Code sessions automatically? Each session is filed under the repository you work in.',
+    )
+  ) {
+    await installHooks()
+    lines.push(
+      'Claude Code sessions are now tracked automatically, by project.' +
+        (ask ? '' : ' (Turn it off with `bestviber tracking off`.)'),
+    )
+  } else {
+    lines.push(
+      'Automatic tracking is off. Turn it on with `bestviber tracking on`.',
+    )
+  }
+  return lines
+}
+
 const sleep = (/** @type {number} */ ms) =>
   new Promise((r) => setTimeout(r, ms))
 
@@ -121,10 +200,11 @@ export const commands = {
             email: me?.user?.email,
           })
           process.stderr.write(' approved.\n')
+          const setup = await setUpAgents()
           return out(
             ctx,
-            { ok: true, email: me?.user?.email },
-            `Signed in as ${me?.user?.email ?? 'you'}.`,
+            { ok: true, email: me?.user?.email, setup },
+            [`Signed in as ${me?.user?.email ?? 'you'}.`, ...setup].join('\n'),
           )
         }
         const err = res.data?.error
@@ -152,7 +232,15 @@ export const commands = {
       if (await token())
         await request('/api/auth/sign-out', { body: {} }).catch(() => {})
       await clearConfig()
-      return out(ctx, { ok: true }, 'Signed out.')
+      const removed = await uninstallHooks().catch(() => false)
+      await clearTrackingState()
+      return out(
+        ctx,
+        { ok: true, trackingRemoved: removed },
+        removed
+          ? 'Signed out, and stopped tracking Claude Code sessions.'
+          : 'Signed out.',
+      )
     },
   },
 
@@ -196,6 +284,12 @@ export const commands = {
       }
       if (ctx.json) return config
       return [
+        ...((await token())
+          ? []
+          : [
+              'Not signed in yet: run `bestviber login` first, or the token below is empty.',
+              '',
+            ]),
         'Claude Code:',
         `  claude mcp add --transport http bestviber ${url} \\`,
         '    --header "Authorization: Bearer $(bestviber token)" \\',
@@ -217,33 +311,9 @@ export const commands = {
     async run(ctx) {
       if (ctx.args[0] !== 'install')
         throw new CliError('Usage: bestviber skill install [--dir <folder>]')
-      // ~/.claude/skills for Claude Code; ~/.agents/skills is the shared
-      // folder other agents read, when it exists.
-      const dirs = ctx.flags.dir
-        ? [String(ctx.flags.dir)]
-        : [
-            join(homedir(), '.claude', 'skills'),
-            ...(existsSync(join(homedir(), '.agents'))
-              ? [join(homedir(), '.agents', 'skills')]
-              : []),
-          ]
-      const files = await Promise.all(
-        ['SKILL.md', 'reference.md'].map(async (name) => {
-          const res = await fetch(`${await baseUrl()}/skill/${name}`)
-          if (!res.ok)
-            throw new CliError(
-              `Could not download ${name} (HTTP ${res.status}).`,
-            )
-          return { name, body: await res.text() }
-        }),
+      const written = await installSkill(
+        ctx.flags.dir ? String(ctx.flags.dir) : undefined,
       )
-      const written = []
-      for (const dir of dirs) {
-        const target = join(dir, 'bestviber')
-        await mkdir(target, { recursive: true })
-        for (const f of files) await writeFile(join(target, f.name), f.body)
-        written.push(target)
-      }
       return out(
         ctx,
         { installed: written },
@@ -252,6 +322,56 @@ export const commands = {
     },
   },
 
+  // Called by Claude Code, not by people: see hooks.mjs.
+  hook: {
+    summary: 'Claude Code hook entry point',
+    actions: [
+      'get_active_session',
+      'start_focus_session',
+      'pause_focus_session',
+      'resume_focus_session',
+      'finish_focus_session',
+    ],
+    hidden: true,
+    async run(ctx) {
+      if (ctx.flags.run) await runHookWorker()
+      else await launchHook()
+      return undefined
+    },
+  },
+
+  tracking: {
+    summary: 'Automatic tracking of Claude Code sessions: on, off or status',
+    usage: 'tracking [on | off]',
+    actions: [],
+    hidden: true,
+    async run(ctx) {
+      const sub = ctx.args[0]
+      if (sub === 'on') {
+        if (!(await token()))
+          throw new CliError('Not signed in. Run `bestviber login` first.', 2)
+        const r = await installHooks()
+        return out(
+          ctx,
+          { on: true, ...r },
+          'Claude Code sessions are tracked automatically.',
+        )
+      }
+      if (sub === 'off') {
+        await uninstallHooks()
+        await clearTrackingState()
+        return out(ctx, { on: false }, 'Automatic tracking is off.')
+      }
+      if (sub) throw new CliError('Usage: bestviber tracking [on | off]')
+      const on = await hooksInstalled()
+      return out(
+        ctx,
+        { on },
+        on ? 'Automatic tracking is on.' : 'Automatic tracking is off.',
+      )
+    },
+  },
+
   // ───── timer ─────
   start: {
     summary: 'Start a focus session',

package/src/format.mjs

@@ -83,5 +83,15 @@ export function stats(stats) {
     for (const t of stats.byTag)
       lines.push(`  ${t.tag.padEnd(16)} ${duration(t.ms)}`)
   }
+
+  if (stats.byProject?.length) {
+    lines.push('', '  by project')
+    const width = Math.max(
+      16,
+      ...stats.byProject.map((/** @type {any} */ p) => p.project.length),
+    )
+    for (const p of stats.byProject)
+      lines.push(`  ${p.project.padEnd(width)} ${duration(p.ms)}`)
+  }
   return lines.join('\n')
 }

package/src/hooks.mjs

@@ -0,0 +1,306 @@
+// Claude Code hooks: install them, and run them.
+//
+// Claude Code runs `bestviber hook` on SessionStart, UserPromptSubmit, Stop
+// and SessionEnd. That command must be instant and silent (stdout on
+// SessionStart and UserPromptSubmit is added to Claude's context, and
+// SessionEnd gets about 1.5 s before exit), so it only hands the event to a
+// detached worker and exits. The worker talks to the server.
+
+import { execFileSync, spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import {
+  appendFile,
+  copyFile,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { call, configPath, token } from './client.mjs'
+import { EMPTY_STATE, decide, projectName } from './tracker.mjs'
+
+const BIN = fileURLToPath(new URL('../bin/bestviber.mjs', import.meta.url))
+const stateDir = () => dirname(configPath())
+const statePath = () => join(stateDir(), 'tracking.json')
+const logPath = () => join(stateDir(), 'hook.log')
+const lockPath = () => join(stateDir(), 'tracking.lock')
+
+// ───── the hook command ─────
+
+/** Read the event from stdin and hand it to a detached worker. Never prints. */
+export async function launchHook() {
+  const payload = await readStdin(2000)
+  try {
+    spawn(process.execPath, [BIN, 'hook', '--run'], {
+      detached: true,
+      stdio: 'ignore',
+      env: { ...process.env, BESTVIBER_HOOK_EVENT: payload },
+    }).unref()
+  } catch {
+    // Tracking is best-effort; never get in the way of Claude Code.
+  }
+}
+
+function readStdin(/** @type {number} */ ms) {
+  return new Promise((resolve) => {
+    let data = ''
+    const done = () => resolve(data)
+    const timer = setTimeout(done, ms)
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', (c) => (data += c))
+    process.stdin.on('end', () => {
+      clearTimeout(timer)
+      done()
+    })
+    process.stdin.on('error', done)
+  })
+}
+
+/** Map a Claude Code hook event to a tracker event, or null to ignore it. */
+function trackerEvent(/** @type {any} */ e) {
+  switch (e?.hook_event_name) {
+    case 'SessionStart':
+      return 'start'
+    case 'UserPromptSubmit':
+      return 'prompt'
+    case 'Stop':
+      return 'reply'
+    case 'SessionEnd':
+      // /clear and /resume also end a session id, but the work goes on.
+      return ['prompt_input_exit', 'logout', 'other'].includes(e.reason)
+        ? 'end'
+        : null
+    default:
+      return null
+  }
+}
+
+// ───── the worker ─────
+
+export async function runHookWorker() {
+  try {
+    const e = JSON.parse(process.env.BESTVIBER_HOOK_EVENT || '{}')
+    const event = trackerEvent(e)
+    if (!event || !(await token())) return
+    await withLock(async () => {
+      const state = await readState()
+      const project = detectProject(e.cwd || process.cwd())
+      const open =
+        event === 'reply'
+          ? state.sessionId
+            ? { id: state.sessionId, status: 'active', project: state.project }
+            : null
+          : await call('get_active_session')
+      const result = decide({ state, open, event, now: new Date(), project })
+      const next = { ...result.state }
+      for (const c of result.calls) {
+        const res = await call(c.name, c.input)
+        if (c.name === 'start_focus_session') next.sessionId = res?.id ?? null
+      }
+      await writeState(next)
+    })
+  } catch (err) {
+    await log(String(/** @type {Error} */ (err)?.stack ?? err))
+  }
+}
+
+function detectProject(/** @type {string} */ cwd) {
+  const git = (/** @type {string[]} */ args) => {
+    try {
+      return (
+        execFileSync('git', ['-C', cwd, ...args], {
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+          timeout: 1500,
+        }).trim() || null
+      )
+    } catch {
+      return null
+    }
+  }
+  return projectName({
+    remote: git(['remote', 'get-url', 'origin']),
+    toplevel: git(['rev-parse', '--show-toplevel']),
+    cwd,
+  })
+}
+
+async function readState() {
+  try {
+    return {
+      ...EMPTY_STATE,
+      ...JSON.parse(await readFile(statePath(), 'utf8')),
+    }
+  } catch {
+    return EMPTY_STATE
+  }
+}
+
+async function writeState(/** @type {object} */ state) {
+  await mkdir(stateDir(), { recursive: true, mode: 0o700 })
+  await writeFile(statePath(), JSON.stringify(state) + '\n', { mode: 0o600 })
+}
+
+export async function clearTrackingState() {
+  await rm(statePath(), { force: true })
+}
+
+/** One worker at a time: a prompt and a reply can land together. */
+async function withLock(/** @type {() => Promise<void>} */ fn) {
+  await mkdir(stateDir(), { recursive: true, mode: 0o700 })
+  const deadline = Date.now() + 8000
+  for (;;) {
+    try {
+      await mkdir(lockPath())
+      break
+    } catch {
+      // A lock older than 30 s belongs to a worker that died.
+      const age = await stat(lockPath())
+        .then((s) => Date.now() - s.mtimeMs)
+        .catch(() => 0)
+      if (age > 30_000) await rm(lockPath(), { recursive: true, force: true })
+      else if (Date.now() > deadline) return
+      else await new Promise((r) => setTimeout(r, 150))
+    }
+  }
+  try {
+    await fn()
+  } finally {
+    await rm(lockPath(), { recursive: true, force: true })
+  }
+}
+
+async function log(/** @type {string} */ line) {
+  try {
+    const size = await stat(logPath())
+      .then((s) => s.size)
+      .catch(() => 0)
+    if (size > 100_000) await rm(logPath(), { force: true })
+    await appendFile(logPath(), `${new Date().toISOString()} ${line}\n`)
+  } catch {
+    // Nowhere left to report to.
+  }
+}
+
+// ───── installing into Claude Code ─────
+
+const claudeDir = () =>
+  process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude')
+const settingsPath = () => join(claudeDir(), 'settings.json')
+
+/** Whether Claude Code is set up on this machine. */
+export const hasClaudeCode = () => existsSync(claudeDir())
+
+/** The command Claude Code runs, with an absolute path (hooks may not share the shell's PATH). */
+function hookCommand() {
+  const q = (/** @type {string} */ s) => `"${s.replace(/(["\\$`])/g, '\\$1')}"`
+  let onPath = null
+  try {
+    onPath = execFileSync('sh', ['-c', 'command -v bestviber'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+  } catch {
+    // Not on PATH (for example run through pnpm dlx).
+  }
+  return onPath ? `${q(onPath)} hook` : `${q(process.execPath)} ${q(BIN)} hook`
+}
+
+const isOurs = (/** @type {any} */ h) =>
+  typeof h?.command === 'string' &&
+  /bestviber(\.mjs)?"?\s+hook$/.test(h.command)
+
+/** Remove our hook entries from every event, keeping everything else. */
+function withoutOurs(/** @type {Record<string, any>} */ hooks) {
+  /** @type {Record<string, any>} */
+  const cleaned = {}
+  for (const [event, groups] of Object.entries(hooks ?? {})) {
+    if (!Array.isArray(groups)) {
+      cleaned[event] = groups
+      continue
+    }
+    const kept = groups
+      .map((g) => ({
+        ...g,
+        hooks: Array.isArray(g?.hooks)
+          ? g.hooks.filter((h) => !isOurs(h))
+          : g?.hooks,
+      }))
+      .filter((g) => !Array.isArray(g.hooks) || g.hooks.length > 0)
+    if (kept.length) cleaned[event] = kept
+  }
+  return cleaned
+}
+
+async function readSettings() {
+  try {
+    return JSON.parse(await readFile(settingsPath(), 'utf8'))
+  } catch (err) {
+    if (/** @type {any} */ (err).code === 'ENOENT') return {}
+    throw new Error(
+      `Could not read ${settingsPath()} (${/** @type {Error} */ (err).message}). Left it unchanged.`,
+    )
+  }
+}
+
+async function writeSettings(/** @type {object} */ settings) {
+  const path = settingsPath()
+  await mkdir(dirname(path), { recursive: true })
+  if (existsSync(path) && !existsSync(`${path}.bestviber-backup`))
+    await copyFile(path, `${path}.bestviber-backup`)
+  const tmp = `${path}.bestviber-tmp`
+  await writeFile(tmp, JSON.stringify(settings, null, 2) + '\n')
+  await rename(tmp, path)
+}
+
+export async function installHooks() {
+  const settings = await readSettings()
+  const command = hookCommand()
+  const entry = { type: 'command', command, timeout: 10 }
+  const hooks = withoutOurs(settings.hooks)
+  /** @type {Array<[string, string | undefined]>} */
+  const events = [
+    ['SessionStart', undefined],
+    ['UserPromptSubmit', undefined],
+    ['Stop', undefined],
+    ['SessionEnd', 'prompt_input_exit|logout|other'],
+  ]
+  for (const [event, matcher] of events)
+    hooks[event] = [
+      ...(hooks[event] ?? []),
+      matcher ? { matcher, hooks: [entry] } : { hooks: [entry] },
+    ]
+  await writeSettings({ ...settings, hooks })
+  return { settings: settingsPath(), command }
+}
+
+export async function uninstallHooks() {
+  if (!existsSync(settingsPath())) return false
+  const settings = await readSettings()
+  const hooks = withoutOurs(settings.hooks)
+  const changed = JSON.stringify(hooks) !== JSON.stringify(settings.hooks ?? {})
+  if (!changed) return false
+  const next = { ...settings, hooks }
+  if (Object.keys(hooks).length === 0) delete next.hooks
+  await writeSettings(next)
+  return true
+}
+
+export async function hooksInstalled() {
+  try {
+    const hooks = (await readSettings()).hooks ?? {}
+    return Object.values(hooks).some(
+      (groups) =>
+        Array.isArray(groups) && groups.some((g) => g?.hooks?.some?.(isOurs)),
+    )
+  } catch {
+    return false
+  }
+}
+
+export const __test = { withoutOurs, isOurs, trackerEvent }

package/src/hooks.test.mjs

@@ -0,0 +1,101 @@
+import { mkdtemp, readFile, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, test } from 'vite-plus/test'
+import {
+  __test,
+  hooksInstalled,
+  installHooks,
+  uninstallHooks,
+} from './hooks.mjs'
+
+const { trackerEvent } = __test
+
+describe('which Claude Code events count', () => {
+  test.each([
+    [{ hook_event_name: 'SessionStart', source: 'startup' }, 'start'],
+    [{ hook_event_name: 'UserPromptSubmit', prompt: 'hi' }, 'prompt'],
+    [{ hook_event_name: 'Stop' }, 'reply'],
+    [{ hook_event_name: 'SessionEnd', reason: 'prompt_input_exit' }, 'end'],
+    [{ hook_event_name: 'SessionEnd', reason: 'logout' }, 'end'],
+    // /clear and /resume end a session id but not the work
+    [{ hook_event_name: 'SessionEnd', reason: 'clear' }, null],
+    [{ hook_event_name: 'SessionEnd', reason: 'resume' }, null],
+    [{ hook_event_name: 'PreToolUse' }, null],
+  ])('%j', (event, expected) => {
+    expect(trackerEvent(event)).toBe(expected)
+  })
+})
+
+describe('installing into ~/.claude/settings.json', () => {
+  let dir = ''
+  const saved = process.env.CLAUDE_CONFIG_DIR
+  const settings = async () =>
+    JSON.parse(await readFile(join(dir, 'settings.json'), 'utf8'))
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'bv-claude-'))
+    process.env.CLAUDE_CONFIG_DIR = dir
+  })
+  afterEach(() => {
+    if (saved === undefined) delete process.env.CLAUDE_CONFIG_DIR
+    else process.env.CLAUDE_CONFIG_DIR = saved
+  })
+
+  const theirs = {
+    theme: 'dark',
+    hooks: {
+      Stop: [{ hooks: [{ type: 'command', command: 'notify-send done' }] }],
+      PreToolUse: [
+        {
+          matcher: 'Bash',
+          hooks: [{ type: 'command', command: './guard.sh' }],
+        },
+      ],
+    },
+  }
+
+  test('adds our four hooks and keeps everything else', async () => {
+    await writeFile(join(dir, 'settings.json'), JSON.stringify(theirs))
+    await installHooks()
+    const s = await settings()
+    expect(s.theme).toBe('dark')
+    expect(s.hooks.PreToolUse).toEqual(theirs.hooks.PreToolUse)
+    expect(s.hooks.Stop[0]).toEqual(theirs.hooks.Stop[0])
+    for (const event of [
+      'SessionStart',
+      'UserPromptSubmit',
+      'Stop',
+      'SessionEnd',
+    ])
+      expect(JSON.stringify(s.hooks[event])).toMatch(/bestviber.*hook/)
+    expect(s.hooks.SessionEnd.at(-1).matcher).toBe(
+      'prompt_input_exit|logout|other',
+    )
+    expect(await hooksInstalled()).toBe(true)
+  })
+
+  test('installing twice does not duplicate', async () => {
+    await installHooks()
+    await installHooks()
+    const s = await settings()
+    expect(s.hooks.UserPromptSubmit).toHaveLength(1)
+  })
+
+  test('uninstall removes only ours', async () => {
+    await writeFile(join(dir, 'settings.json'), JSON.stringify(theirs))
+    await installHooks()
+    expect(await uninstallHooks()).toBe(true)
+    const s = await settings()
+    expect(s).toEqual(theirs)
+    expect(await hooksInstalled()).toBe(false)
+  })
+
+  test('a settings file that is not valid JSON is left alone', async () => {
+    await writeFile(join(dir, 'settings.json'), '{ not json')
+    await expect(installHooks()).rejects.toThrow(/Left it unchanged/)
+    expect(await readFile(join(dir, 'settings.json'), 'utf8')).toBe(
+      '{ not json',
+    )
+  })
+})

package/src/tracker.mjs

@@ -0,0 +1,108 @@
+// Automatic tracking for Claude Code: what to do when a hook fires.
+//
+// Pure: given the saved state, the session the server says is open, the
+// event and the time, return the API calls to make and the next state. The
+// hook runner (hooks.mjs) does the I/O; the tests drive this directly.
+//
+// Rules (agreed with the product owner):
+// - A prompt, or Claude Code starting, makes sure a session is running for
+//   the current project. A different project's session is closed first.
+// - Claude finishing a reply counts as activity; no API call is needed.
+// - Quiet under GRACE (reading a reply) still counts as focus.
+// - Quiet from GRACE up to FINISH is recorded as a pause in the same session.
+// - Quiet of FINISH or more ends the session when the quiet began; the next
+//   prompt starts a new one.
+// - A session someone started by hand (CLI, app, agent) is left alone.
+
+export const GRACE_MS = 2 * 60_000
+export const FINISH_MS = 10 * 60_000
+
+/**
+ * @typedef {{ sessionId: string | null, project: string | null, lastActivity: string | null }} TrackerState
+ * @typedef {{ id: string, status: string, project?: string | null } | null} OpenSession
+ * @typedef {'start' | 'prompt' | 'reply' | 'end'} TrackerEvent
+ * @typedef {{ name: string, input: Record<string, unknown> }} Call
+ */
+
+/** @type {TrackerState} */
+export const EMPTY_STATE = {
+  sessionId: null,
+  project: null,
+  lastActivity: null,
+}
+
+/**
+ * @param {{ state: TrackerState, open: OpenSession, event: TrackerEvent, now: Date, project: string }} input
+ * @returns {{ calls: Array<Call>, state: TrackerState }}
+ */
+export function decide({ state, open, event, now, project }) {
+  const nowIso = now.toISOString()
+  const last = state.lastActivity ? new Date(state.lastActivity) : null
+  const gap = last ? now.getTime() - last.getTime() : 0
+  const ours = open !== null && open.id === state.sessionId
+  /** When the work in the open session really stopped. */
+  const endedAt = last && gap >= GRACE_MS ? state.lastActivity : nowIso
+
+  // Someone else's session is open: stay out of its way.
+  if (open && !ours)
+    return {
+      calls: [],
+      state: { sessionId: null, project: null, lastActivity: nowIso },
+    }
+
+  if (event === 'reply')
+    return { calls: [], state: { ...state, lastActivity: nowIso } }
+
+  if (event === 'end') {
+    if (!ours) return { calls: [], state: EMPTY_STATE }
+    return {
+      calls: [{ name: 'finish_focus_session', input: { at: endedAt } }],
+      state: EMPTY_STATE,
+    }
+  }
+
+  // 'start' or 'prompt': make sure this project's session is running.
+  /** @type {Array<Call>} */
+  const calls = []
+  const start = { name: 'start_focus_session', input: { project } }
+
+  if (!ours) calls.push(start)
+  else if (open.project !== project || gap >= FINISH_MS) {
+    calls.push({ name: 'finish_focus_session', input: { at: endedAt } }, start)
+  } else if (gap >= GRACE_MS) {
+    calls.push(
+      { name: 'pause_focus_session', input: { at: state.lastActivity } },
+      { name: 'resume_focus_session', input: {} },
+    )
+  }
+
+  return {
+    calls,
+    // A new session's id comes back from start_focus_session; the runner
+    // fills it in.
+    state: {
+      sessionId: calls.includes(start) ? null : state.sessionId,
+      project,
+      lastActivity: nowIso,
+    },
+  }
+}
+
+/**
+ * The project for a working directory: "owner/repo" from the git remote,
+ * else the repository folder name, else the folder name.
+ *
+ * @param {{ remote: string | null, toplevel: string | null, cwd: string }} where
+ */
+export function projectName({ remote, toplevel, cwd }) {
+  if (remote) {
+    // git@github.com:owner/repo.git, https://host/owner/repo(.git), ssh://…
+    const m = remote
+      .trim()
+      .replace(/\.git$/, '')
+      .match(/[:/]([^/:]+\/[^/:]+)$/)
+    if (m?.[1]) return m[1]
+  }
+  const dir = (toplevel || cwd).replace(/\/+$/, '')
+  return dir.slice(dir.lastIndexOf('/') + 1) || dir
+}

package/src/tracker.test.mjs

@@ -0,0 +1,174 @@
+import { describe, expect, test } from 'vite-plus/test'
+import { EMPTY_STATE, decide, projectName } from './tracker.mjs'
+
+const at = (hm) => new Date(`2026-11-02T${hm}:00Z`)
+const iso = (hm) => at(hm).toISOString()
+const P = 'amar/bestviber'
+const mine = (overrides = {}) => ({
+  id: 's1',
+  status: 'active',
+  project: P,
+  ...overrides,
+})
+const tracking = (lastHm, overrides = {}) => ({
+  sessionId: 's1',
+  project: P,
+  lastActivity: iso(lastHm),
+  ...overrides,
+})
+
+describe('automatic tracking', () => {
+  test('the first prompt starts a session for the project', () => {
+    const r = decide({
+      state: EMPTY_STATE,
+      open: null,
+      event: 'prompt',
+      now: at('09:00'),
+      project: P,
+    })
+    expect(r.calls).toEqual([
+      { name: 'start_focus_session', input: { project: P } },
+    ])
+    expect(r.state.lastActivity).toBe(iso('09:00'))
+  })
+
+  test('a quick next prompt changes nothing', () => {
+    const r = decide({
+      state: tracking('09:00'),
+      open: mine(),
+      event: 'prompt',
+      now: at('09:01'),
+      project: P,
+    })
+    expect(r.calls).toEqual([])
+    expect(r.state.sessionId).toBe('s1')
+  })
+
+  test('quiet between 2 and 10 minutes becomes a pause in the same session', () => {
+    const r = decide({
+      state: tracking('09:00'),
+      open: mine(),
+      event: 'prompt',
+      now: at('09:06'),
+      project: P,
+    })
+    expect(r.calls).toEqual([
+      { name: 'pause_focus_session', input: { at: iso('09:00') } },
+      { name: 'resume_focus_session', input: {} },
+    ])
+    expect(r.state.sessionId).toBe('s1')
+  })
+
+  test('quiet of 10 minutes or more ends the session when the quiet began', () => {
+    const r = decide({
+      state: tracking('09:00'),
+      open: mine(),
+      event: 'prompt',
+      now: at('09:30'),
+      project: P,
+    })
+    expect(r.calls).toEqual([
+      { name: 'finish_focus_session', input: { at: iso('09:00') } },
+      { name: 'start_focus_session', input: { project: P } },
+    ])
+    expect(r.state.sessionId).toBeNull()
+  })
+
+  test('switching repositories closes the old project and starts the new one', () => {
+    const r = decide({
+      state: tracking('09:00'),
+      open: mine(),
+      event: 'prompt',
+      now: at('09:01'),
+      project: 'amar/website',
+    })
+    expect(r.calls).toEqual([
+      { name: 'finish_focus_session', input: { at: iso('09:01') } },
+      { name: 'start_focus_session', input: { project: 'amar/website' } },
+    ])
+  })
+
+  test('a finished reply is activity, with no API call', () => {
+    const r = decide({
+      state: tracking('09:00'),
+      open: mine(),
+      event: 'reply',
+      now: at('09:04'),
+      project: P,
+    })
+    expect(r.calls).toEqual([])
+    expect(r.state.lastActivity).toBe(iso('09:04'))
+  })
+
+  test('Claude Code exiting finishes the session, at the last activity if it was quiet', () => {
+    expect(
+      decide({
+        state: tracking('09:00'),
+        open: mine(),
+        event: 'end',
+        now: at('09:20'),
+        project: P,
+      }).calls,
+    ).toEqual([{ name: 'finish_focus_session', input: { at: iso('09:00') } }])
+    expect(
+      decide({
+        state: tracking('09:00'),
+        open: mine(),
+        event: 'end',
+        now: at('09:01'),
+        project: P,
+      }).calls,
+    ).toEqual([{ name: 'finish_focus_session', input: { at: iso('09:01') } }])
+  })
+
+  test('a session someone started by hand is left alone', () => {
+    const r = decide({
+      state: EMPTY_STATE,
+      open: { id: 'manual', status: 'active', project: null },
+      event: 'prompt',
+      now: at('09:00'),
+      project: P,
+    })
+    expect(r.calls).toEqual([])
+    expect(r.state.sessionId).toBeNull()
+  })
+
+  test('if our session was closed elsewhere, the next prompt starts a new one', () => {
+    const r = decide({
+      state: tracking('09:00'),
+      open: null,
+      event: 'prompt',
+      now: at('09:01'),
+      project: P,
+    })
+    expect(r.calls).toEqual([
+      { name: 'start_focus_session', input: { project: P } },
+    ])
+  })
+})
+
+describe('project names', () => {
+  test.each([
+    ['git@github.com:amaralazizy/bestviber.git', 'amaralazizy/bestviber'],
+    ['https://github.com/amaralazizy/bestviber.git', 'amaralazizy/bestviber'],
+    ['https://gitlab.com/team/app', 'team/app'],
+    ['ssh://git@host:2222/team/app.git', 'team/app'],
+  ])('%s', (remote, expected) => {
+    expect(projectName({ remote, toplevel: '/x/y', cwd: '/x/y/z' })).toBe(
+      expected,
+    )
+  })
+
+  test('falls back to the repository folder, then the working folder', () => {
+    expect(
+      projectName({
+        remote: null,
+        toplevel: '/home/a/notes',
+        cwd: '/home/a/notes/src',
+      }),
+    ).toBe('notes')
+    expect(
+      projectName({ remote: null, toplevel: null, cwd: '/home/a/scratch/' }),
+    ).toBe('scratch')
+  })
+})