---
name: bestviber
description: Track the user's focus time with bestviber and answer questions about it. Use when the user starts or finishes a block of work ("starting on X", "taking a break", "done for today"), asks to start, pause or stop a timer, or asks how much, when or how consistently they focused today, yesterday, this week, month or year (totals, streaks, peak hours, tags, trends). Uses the bestviber CLI or the bestviber MCP tools.
---

# bestviber

bestviber is the user's focus timer. You run it for them: start a session
when they start working, pause it for breaks, finish it when they are done,
and answer questions about their focus with real numbers instead of guesses.

## Setup (once)

Check with `bestviber whoami`. If the command is missing, install it with
`npm install -g bestviber`. If it says not signed in, run `bestviber login`.
It prints a URL and a code and waits until the user approves the code in
their browser, so run it in the background (or ask the user to run
`! bestviber login` themselves) and tell them to approve it. Login also
installs this skill and turns on automatic tracking of Claude Code sessions.

If the bestviber MCP tools (`get_stats`, `start_focus_session`, …) are
already available to you, use those instead of the CLI. Same actions, same
results.

## Automatic tracking

Check with `bestviber tracking`. When it is on, Claude Code hooks time every
session and file it under the repository being worked in: you do not need to
start or stop anything, and you should not, unless the user asks. A session
the user starts by hand is left alone by the hooks. To turn it off or on:
`bestviber tracking off` / `bestviber tracking on`.

## Running the timer by hand

| When the user…              | Run                                                     |
| --------------------------- | ------------------------------------------------------- |
| starts working on something | `bestviber start` (add `--tag <name>` if they use tags) |
| takes a break               | `bestviber pause`                                       |
| comes back                  | `bestviber resume`                                      |
| is done with the block      | `bestviber stop --note "<what they did>"`               |
| asks what is running        | `bestviber status`                                      |

- Starting a session finishes any session still open (running or paused), so check
  `bestviber status` first if you are not sure.
- Write the note from what actually happened in the conversation: a short
  phrase like "refactored auth forms", not "work session".
- Only start or stop the timer when the user asked to, or when they clearly
  said they are starting or finishing work. Do not leave a timer running
  silently: say that you started it.

## Answering questions about focus

| Question                                     | Run                                                                                      |
| -------------------------------------------- | ---------------------------------------------------------------------------------------- |
| "How much have I focused today / this week?" | `bestviber today`, `bestviber week`                                                      |
| "How was my month / year?"                   | `bestviber month`, `bestviber year`                                                      |
| a specific day or range                      | `bestviber stats --date 2026-10-14`, `bestviber stats --from 2026-10-01 --to 2026-10-15` |
| "Am I on a streak?"                          | `bestviber streak`                                                                       |
| "When do I focus best?", "any patterns?"     | `bestviber insights`, plus `bestviber month` for the by-hour breakdown                   |
| "What did I work on yesterday?"              | `bestviber sessions --date yesterday`                                                    |

Add `--json` to any command when you need exact numbers to compute with.
Durations in JSON are milliseconds. Present them as hours and minutes
("2h 15m"), never as raw milliseconds.

When reporting, lead with the answer ("You focused 4h 10m this week, 20%
more than last week"), then one or two details worth knowing (best day, peak
hours, streak). Do not dump the whole report unless asked.

## Everything else

`bestviber tools` lists every action the server offers, including ones added
after this skill was written, and `bestviber run <action> --key value` runs
any of them. The full reference with inputs is in [reference.md](reference.md).

## Errors

- `Not signed in` (exit code 2): run `bestviber login` and have the user
  approve the code.
- `No focus session is open`: nothing is running; nothing to pause or stop.
- Anything else: show the user the message as-is.
