Start a millisecond-precision stopwatch (or countdown) on the TimerMCP server.

The server stamps the start on a MONOTONIC nanosecond clock the instant this call arrives. Elapsed time is computed server-side as stop-stamp minus start-stamp, so the constant part of the pipeline delay (user → Claude → server) cancels out between start and stop — only the difference in latency between the two calls can leak in.

Args:

• name (string, default "main"): Timer name. NAME IT AFTER THE TASK — when the user says what they are working on ("start a timer for the auth refactor"), use that as the name ("auth refactor") so their session log reads like a work journal. Pass a comma-separated list (e.g. "alice,bob") to start several timers on the SAME nanosecond — race mode.

• target_ms (number, optional): Turns the run into a countdown (Pomodoro, rest interval, speedrun target). Stop reports over/under.

• announcer ('hype'|'zen'|'sergeant'|'sports'|'minimal', optional): Voice for this run's announcements. Defaults to configured style.

• start_offset_ms (number, optional): Milliseconds subtracted from the final elapsed to bias out start-side latency. Defaults to configured value (0).

Returns: { started: [{name, elapsed_ms, started_wall, target_ms?}], announcement, dashboard_url }

IMPORTANT: Relay the 'announcement' line to the user with matching energy — you are the track announcer. Mention the dashboard_url the first time so they can put the live wall display on a second screen.

Errors: fails if a timer with the same name is already running (stop or cancel it first, or pick another name).

Stop a running timer and get the official elapsed time in milliseconds.

elapsed_ms = (monotonic stop-stamp − monotonic start-stamp) − start_offset_ms − stop_offset_ms. raw_elapsed_ms is the pure unadjusted monotonic difference. Because both stamps are taken server-side, symmetric pipeline latency cancels; offsets exist only to bias out asymmetry if the user wants.

Args:

• name (string, default "main"): Which timer to stop.

• stop_offset_ms (number, optional): Override the configured stop-side latency handicap for this stop only.

• trim_to_ms (number, optional): Cap the recorded time. Use when the user forgot to stop a runaway timer and tells you how long they actually worked (e.g. "I only worked 25 minutes" → trim_to_ms 1500000). The session records the capped time and is flagged trimmed.

Returns: { session: {name, elapsed_ms, raw_elapsed_ms, formatted, splits, pb, pb_margin_ms?, target_ms?, over_under_ms?, id}, announcement, card_path, card_url }

A shareable SVG result card is written on every stop (card_path on disk, card_url served by the dashboard).

IMPORTANT: Relay the 'announcement' to the user — big finish energy if it's a PB. Quote the exact millisecond figure.

Record a split (lap) on a running timer without stopping it — speedrun style.

If a personal-best run exists for this timer name, the split is compared against the SAME split index on the PB run and delta_vs_best_ms is returned (negative = ahead of PB pace, like LiveSplit green).

Args:

• name (string, default "main"): Running timer to split.

• label (string, optional): Name the checkpoint, e.g. "deploy done", "lap 2". Defaults to "Split N".

Returns: { name, index, label, at_ms, formatted, delta_vs_best_ms?, announcement }

Relay the announcement; if delta_vs_best_ms is present, call out ahead/behind PB pace.

Check what's on the clock right now. Read-only.

Args:

• name (string, optional): One timer, or omit for all running timers.

Returns: { running: [{name, elapsed_ms, formatted, target_ms?, remaining_ms?, splits, best_ms?, recovered, runaway}], count, dashboard_url } 'recovered' = true means the server restarted mid-run and that timer fell back to wall-clock precision. 'runaway' = true means the timer has been running longer than the configured max_hours (default 4) — the user probably forgot it. Ask if they want to stop it, offering trim_to_ms to cap the recorded time at what they actually worked. elapsed_ms is a live server-side reading at the moment this call was processed.

Discard a running timer WITHOUT recording a session, PB, or history entry. Use for false starts ("wait, I wasn't ready"). The would-be elapsed is returned for reference only.

Args:

• name (string, default "main"): Timer to discard.

Returns: { name, discarded_elapsed_ms }

Personal bests, recent finished runs, and lifetime totals. Read-only.

Args:

• name (string, optional): Filter to one timer name; omit for everything.

• limit (number, default 10): Max recent sessions returned (1–50).

Returns: { bests: [{name, best_ms?, count, total_ms}], recent: [{id, name, elapsed_ms, formatted, pb, splits, stopped_wall, target_ms?, over_under_ms?}], lifetime_ms, lifetime_sessions }

Great for "what's my record?", "how much have I tracked today?", or building a leaderboard recap for the user.

Read or update TimerMCP settings. Call with no args to read.

Settings:

• announcer ('hype'|'zen'|'sergeant'|'sports'|'minimal'): Default announcement personality. Styles: hype, zen, sergeant, sports, minimal.

• start_offset_ms / stop_offset_ms (number ≥ 0): Latency handicaps subtracted from every elapsed. Leave at 0 for most uses — symmetric pipeline latency already cancels because both timestamps are taken server-side on a monotonic clock. Set these only to bias out a known asymmetry (e.g. user reckons their "stop" reaches the server ~300ms slower than their "start").

• max_hours (number): A running timer older than this is flagged runaway (default 4).

• sync_token (string): Enables cloud auto-sync. The user gets this token from their dashboard at https://timermcp.vercel.app/app ("set my timer sync token to …"). Every finished run then syncs automatically. Pass an empty string to disable sync.

• sync_url (string): Override the cloud endpoint (default https://timermcp.vercel.app).

Returns: { config: {announcer, start_offset_ms, stop_offset_ms, max_hours, sync_enabled, sync_token_tail?, sync_url?}, dashboard_url, data_dir }