BurrowTime MCP server
Commit Nov 4, 2026Enables coding agents and developers to track time locally using a CLI, TUI, or MCP server with Watson compatibility.
Also known as fabean/BurrowTime
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 4, 2026
- License
- MIT
What is BurrowTime MCP?
BurrowTime enables coding agents and developers to track time locally using a CLI, TUI, or MCP server with Watson compatibility.
Summary generated from the project's README
About BurrowTime MCP server
Developers and coding agents can track work time locally using BurrowTime, a tool designed to manage time tracking through a CLI, a terminal UI, or an MCP server. It is built as a Go-based successor to Watson, maintaining compatibility with existing Watson data formats and commands while adding an interactive Bubble Tea dashboard. The system is local-first, storing all time data in ordinary files on your machine without requiring any hosted services or database installations.
Coding agents like Claude Code, Cursor, and Gemini can use specific skills or the MCP server to manage sessions. These agents can start, pause, resume, and stop timers that they explicitly own, ensuring they only track work you have requested. The MCP server implementation allows agents to use tools for heartbeats, status checks, and recovery. For manual use, the terminal UI provides live dashboards, report charts, and interactive filtering to manage projects and tags.
What you can do with it
- 1Automated agent time trackingInstruct a coding agent to track a specific task under a project name.
- 2Visualizing time reportsUse the interactive terminal dashboard to view weekly reports and filter activity.
- 3Migrating from WatsonImport existing time tracking history from a Watson installation into BurrowTime.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
BURROWTIME_DIRTIMETABLE_TOKEN
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablefabean/burrowtime is public and reachablegithub.com/fabean/burrowtime ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-04github.com/fabean/burrowtime ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubBurrowTime
Open-source time tracking for coding agents and developers. Local files, a friendly terminal UI, and Watson-compatible commands and data.
Website · Agent setup · Documentation · Releases
BurrowTime is a local-first time tracker for people and coding agents. Codex, Claude Code, Cursor, Gemini CLI, OpenCode, and MCP clients can track only the work you explicitly request. Agent sessions have exact ownership, safe retries, leases for interrupted work, and pause or resume support. Your time stays in ordinary files on your machine.
It is also a Go port of Watson, the command-line time tracker. BurrowTime adds an interactive Bubble Tea dashboard while preserving Watson's commands and on-disk format. Existing Watson users can copy their history into BurrowTime on first launch and move it back later. No conversion, account, or hosted service is required.
$ burrowtime start "client portal" +review
Starting project client portal [review] at 09:42
$ burrowtime stop
Stopping project client portal [review], started 38 minutes ago and stopped just now. (id: 82fd91a)
$ burrowtime report --week
Mon 17 August 2026 -> Mon 17 August 2026
client portal - 2h 14m 08s
Track coding-agent time in one minute
Install the bundled skill for your agent, check the setup, then name a project and task in your prompt:
burrowtime skill install codex
burrowtime skill doctor codex
Track this work in BurrowTime under "client portal" +PORTAL-42.
The agent starts an owned local timer, renews its lease during long work, pauses when it must wait for required input, and stops that exact session at the end. It cannot silently start tracking, and it never needs to stop your other timers. See the agent time tracking guide for every supported client, MCP setup, repository defaults, and protocol rules.
Why BurrowTime?
- A real terminal UI. Run
burrowtimeby itself for a live dashboard, recent activity, interactive logs, report charts, date ranges, and filtering. - A scriptable CLI. Direct commands, JSON, CSV, pipes, shell completions, and stable exit codes remain first-class features.
- Built for coding agents. Codex, Claude Code, Cursor, Gemini, OpenCode, and MCP clients can track only the work you request, without taking control of unrelated timers.
- Watson-compatible data. BurrowTime uses Watson's
config,frames,state, andlast_syncformats in its own safe data directory. - Local by default. Your time data stays in ordinary files on your machine.
- One small Go program. No Python environment or database is required.
BurrowTime compared with Watson
BurrowTime preserves Watson's familiar workflow, but it is not merely a renamed Watson executable:
| Area | Watson 2.1.0 | BurrowTime |
|---|---|---|
| Runtime | Python application | Standalone Go binaries |
| Running with no command | Non-interactive CLI behavior | Bubble Tea dashboard |
| CLI commands and output | Original behavior | Watson-compatible behavior, JSON, CSV, and exit codes |
| Data location | Watson directory and WATSON_DIR |
Separate BurrowTime directory and BURROWTIME_DIR |
| Data format | config, frames, state, last_sync |
Same formats, plus companion files for concurrency and agent sessions |
| Active timers | One | One by default, with explicit concurrent timers available |
| Coding agents | No dedicated workflow | Owned sessions, safe retries, leases, skills, and MCP tools |
| Stopping multiple timers | Not applicable | Interactive picker, --timer, or --all |
| Logs and reports | CLI output and filters | Compatible CLI plus interactive views, charts, ranges, and filters |
| Moving data | Operates directly on its own directory | Copies data from or back to Watson with confirmation and backups |
| Safety differences | Original behavior | Guards two known crash/data-corruption edge cases described below |
The release archive also includes a watson compatibility executable. Unlike
the primary burrowtime command, that executable keeps Watson's data-directory
and non-interactive bare-command behavior for users who want a direct Go-based
replacement.
Installation
Go install
With Go 1.24 or newer:
go install github.com/fabean/BurrowTime/cmd/burrowtime@latest
The optional drop-in watson executable can be installed alongside it:
go install github.com/fabean/BurrowTime/cmd/watson@latest
Release archives
Tagged releases provide checksummed archives for Linux, macOS, and Windows on
the GitHub Releases page. Each
archive contains both burrowtime and the optional watson compatibility
binary.
Agent time tracking
The BurrowTime binary contains an optional skill for coding agents. Downloading the binary does not install or activate the skill. Install it once for your agent:
burrowtime skill install codex
burrowtime skill install claude
burrowtime skill install cursor
burrowtime skill install gemini
burrowtime skill install opencode
# Install the shared skill plus Claude Code's copy.
burrowtime skill install all
Codex, Cursor, Gemini, and OpenCode share the copy under
~/.agents/skills/track-time-with-burrowtime. Claude Code uses
~/.claude/skills/track-time-with-burrowtime. The skill does not track ordinary
chats. Ask for tracking in the task prompt:
Track this work in BurrowTime under "client portal" +PORTAL-42.
If the project or task is missing, the skill asks for it before starting work.
It checks the installed binary's agent protocol, creates an agent session,
renews its lease during long work, pauses while waiting for required input, and
stops that exact session at the end. Check the installation and the binary on
your PATH with:
burrowtime skill doctor codex
burrowtime skill doctor all
This catches an old binary paired with a newer skill. To replace local changes with the files bundled in the current binary, run:
burrowtime skill install codex --force
Releases before the shared installer used
~/.codex/skills/track-time-with-burrowtime. The installer warns when that
legacy copy is still present, and skill doctor treats it as a duplicate so
you can remove it deliberately.
Agents without compatible skill discovery can use BurrowTime's MCP server.
Configure the agent to launch burrowtime mcp over standard input and output.
A typical MCP entry is:
{
"mcpServers": {
"burrowtime": {
"command": "burrowtime",
"args": ["mcp"]
}
}
}
The MCP server provides start, heartbeat, pause, resume, stop, status, recovery, reporting, and capability tools. The same explicit-request rule still applies. An agent should start tracking only when you ask it to.
Package-manager recipes will be advertised here only after their first release has been published and tested. Maintainers can follow the distribution guide for AUR, Homebrew, and Scoop.
Build from source
git clone https://github.com/fabean/BurrowTime.git
cd burrowtime
make build
./bin/burrowtime
Getting started
Start and stop a timer from the CLI:
burrowtime start "deep work" +planning
burrowtime status
burrowtime stop
Projects may contain spaces. Tags begin with +; both are carried into logs
and reports.
burrowtime start "acme redesign" +frontend +meeting
Run BurrowTime without a subcommand to open the dashboard:
burrowtime
On the first interactive use, BurrowTime checks whether its default data directory is empty. If it finds an existing Watson installation, it offers to copy that data into BurrowTime; pressing Enter accepts. Watson's original files are never moved or changed. Declining is remembered, and scripts are never blocked waiting for this prompt. You can still import manually later.
The dashboard and direct CLI use the same storage and reporting code. Actions started in the TUI are handed to the normal command implementation, so there is no separate or reduced interactive mode.
Concurrent timers
With the default settings, starting another project remains safe: if any timer
is active, an ordinary start opens an interactive chooser. You can stop all
active timers and replace them with the new one, or keep them running and start
the new timer concurrently. Press Escape to leave everything unchanged.
Scripts and redirected commands never wait for the TUI. They receive the
existing already started error and must choose the behavior explicitly:
# Stop every active timer, then start this one.
burrowtime start --stop "client call" +meeting
# Keep existing timers running and add another.
burrowtime start --concurrent "background export" +ops
# Return the new timer ID for an agent or script.
burrowtime start --concurrent --json "background export" +ops
If Watson's options.stop_on_start setting is enabled, --no-stop restores
the refuse-to-replace behavior for one invocation. --stop and --concurrent
cannot be combined, and a concurrent timer cannot use --no-gap.
burrowtime status lists every active timer and its short ID. With multiple
timers, an interactive burrowtime stop opens a picker. Scripts must be
explicit:
burrowtime stop --timer 4e169a2
burrowtime stop --all
The Watson-compatible state file continues to hold one primary timer.
Additional timers are stored in BurrowTime's active_timers companion file;
when the primary is stopped, another active timer is promoted automatically.
Every completed timer is written as an ordinary Watson frame. Reports count
each timer's full duration, so overlapping time contributes independently to
each project and to the combined total.
Agent-owned sessions
Agent sessions are metadata around standard BurrowTime timers. They do not create a second kind of billable record. A completed session still becomes an ordinary Watson frame and appears in normal logs and reports.
Start a session directly with:
burrowtime agent start \
--client codex \
--project "client portal" \
--task PORTAL-42 \
--lease 30m \
--json
The JSON result contains session.id. Agent integrations retain that ID and
use it for every later action:
burrowtime agent heartbeat --session <session-id> --json
burrowtime agent pause --session <session-id> --json
burrowtime agent resume --session <session-id> --json
burrowtime agent stop --session <session-id> --json
agent start accepts --owner for a conversation or run ID and
--idempotency-key for safe retries. Leases prevent an interrupted agent from
leaving an unbounded timer behind. Run burrowtime agent recover to close
expired sessions at their lease deadline. burrowtime agent status lists
sessions, and burrowtime agent report groups recorded time by session and
client.
You can still stop an agent's active timer with normal commands or the TUI.
burrowtime stop works when it is the only timer. With several timers, select
it in the picker or pass --timer. BurrowTime marks the session
manually_stopped, and a later agent stop succeeds without changing anything.
A repository can provide defaults for direct agent commands in its nearest
.burrowtime.toml:
[agent]
project = "client portal"
task = "PORTAL-42"
repository = "portal-app"
lease = "30m"
task_from_branch = false
Set task_from_branch = true to infer ticket-shaped values such as
PORTAL-42 from the current Git branch when task is omitted. Explicit flags
take precedence. The bundled skill itself asks the user when the project or
task was not supplied, so repository defaults do not turn tracking on.
Use burrowtime capabilities --json to inspect the supported agent protocol,
MCP version, skill targets, session states, and individual features.
Command overview
| Command | Purpose |
|---|---|
burrowtime |
Open the interactive dashboard |
start, stop, status |
Control and inspect live timers |
restart, cancel |
Resume a frame or discard a running timer |
add, edit, remove |
Maintain historical frames |
log |
List individual sessions |
report |
Summarize time by project |
aggregate |
Aggregate project time by day |
projects, tags, frames |
List known values and frame IDs |
rename, merge |
Rewrite names or merge a frames file |
config |
Read or update Watson-compatible settings |
sync |
Synchronize with a Watson-compatible server |
migrate |
Copy data between BurrowTime and Watson |
agent |
Control and report agent-owned sessions |
capabilities |
Show the machine-readable agent protocol |
mcp |
Run the BurrowTime MCP server over stdio |
skill |
Install and diagnose bundled agent skills |
completion |
Generate shell completion scripts |
TUI controls
| Key | Action |
|---|---|
↑ / ↓, j / k |
Move or scroll |
enter |
Open the selected action |
l / r / a |
Open Log, Report, or Aggregate from the dashboard |
e |
Select a completed Log session to edit |
s / x |
Start or stop a timer |
← / → |
Change the report range |
/ |
Filter by project, tag, frame ID, or date |
tab |
Cycle between Log, Report, and Aggregate |
m |
Toggle session messages in the current Log, Report, or Aggregate view |
b / esc |
Go back |
q |
Quit |
Mouse-wheel scrolling also works in the Log and Report views.
The Aggregate view groups the selected date range by day, project, and
ticket/tag. It uses the same range selector and text filter as Log and Report;
press ←/→ to change the range and / to filter projects, tags, IDs, or
dates. Untagged time remains included in project and daily totals.
From Log, press e to select a completed session, use arrows or j/k to
move, and press Enter to edit it. Press / to search by project, tag, date,
or session ID. In the editor, use arrows or Tab to choose a field, press Enter
to edit it, and use Ctrl+U to clear a field before typing. Press s from the
form or Ctrl+S while editing a field to review the save summary, then press
Enter to confirm. Or select Save Changes and press Enter. Esc cancels
selection, the current field edit, or the editor without saving. The selection
list skips active timers and completed agent-owned sessions; use the existing edit ID
command for an active primary timer.
The guided form uses the flexible timestamp formats supported by the CLI parser. Time-only values use the selected session's original date (the end field keeps its own date for overnight sessions). Messages can also be edited in the form and remain stored separately from tags.
The CLI also supports guided selection and editing:
burrowtime edit --interactive
burrowtime edit -i
burrowtime edit -i 5f3a9c1
An optional ID opens the selector with that session preselected. The normal
burrowtime edit ID external-editor workflow remains available.
Export time to Clockify
Install the optional burrowtime-clockify executable alongside BurrowTime.
The latest release archive includes it, or install both executables with Go:
go install github.com/fabean/BurrowTime/cmd/burrowtime@latest
go install github.com/fabean/BurrowTime/cmd/burrowtime-clockify@latest
Configure a workspace and user using CLOCKIFY_WORKSPACE_ID,
CLOCKIFY_USER_ID, and CLOCKIFY_API_KEY, then run:
burrowtime clockify configure --rounding up --increment 15m
burrowtime clockify sync --today --dry-run
burrowtime clockify sync --today
Sync suggests Clockify projects for unmapped local projects and shows their clients so similarly named projects are distinguishable. Search, select a mapping, then review and edit descriptions, destinations, durations, and billable settings before confirming the upload. Rounding applies to each completed entry; matching entries on the same local day are then combined into one upload, starting at the earliest entry and lasting the sum of the rounded durations. Project, tags, and billable status must match. Local times stay exact. Local receipts remember successful uploads so reruns skip them. Uncertain uploads require reconciliation before retrying.
Descriptions contain only your tags: burrowtime start sema +SEMA-123
exports SEMA-123, without the project name, +, or an internal tracking ID.
Multiple tags are sorted and space-separated; entries without tags have an
empty description unless you edit it. Named connections let you route local
projects to different Clockify workspaces. Nothing syncs in the background.
See Clockify setup, mapping, and recovery for installation from this checkout, configuration, dry-run, and unattended sync.
Export time to Timetable
Install the optional burrowtime-timetable connector, then create a personal
token in Timetable Settings. Configure its site URL and user ID, map local
projects, and preview before uploading:
go install github.com/fabean/BurrowTime/cmd/burrowtime-timetable@latest
export TIMETABLE_TOKEN='your-personal-token'
burrowtime timetable configure --user YOUR_TIMETABLE_USER_ID
burrowtime timetable projects
burrowtime timetable map 'local project' TIMETABLE_PROJECT_UUID
burrowtime timetable sync --today --dry-run
burrowtime timetable sync --today
Timetable also combines matching entries per local day after applying rounding. Combined uploads use the earliest start and summed durations, with stable IDs for safe retries. Clockify and Timetable mappings and receipts are independent. See Timetable setup and recovery.
Logs, reports, and filters
Use a shortcut range or explicit dates:
burrowtime log --day
burrowtime log --month --project "client portal"
burrowtime report --week --tag billable
burrowtime report --from 2026-08-01 --to 2026-08-15
burrowtime aggregate --from 2026-01-01 --to 2026-12-31
Time inputs accept 24-hour values such as 14:30 and AM/PM values such as
2:30 PM. When a time has no date, BurrowTime uses today in your local
timezone. Add an explicit date for historical work; today and yesterday
may also precede a time:
burrowtime start RAF +RAF-326 --at "9am"
burrowtime stop --at "11:30 AM"
burrowtime add --from "9:30 AM" --to "11:15 AM" RAF +RAF-326
burrowtime add --from "2026-10-26 9:30 AM" --to "2026-10-26 11:15 AM" RAF +RAF-326
burrowtime stop --at "yesterday 2:30 PM"
Live timers retain second-level start and stop times by default. To floor automatically captured live timer boundaries to the start of the current minute, enable minute precision:
burrowtime config options.time_precision minute
This applies to ordinary BurrowTime starts, stops, restarts, and concurrent
human timers. Explicit timestamps without seconds already resolve to :00;
explicit seconds are preserved. Agent-owned timers and existing saved sessions
are not rewritten. Set options.time_precision to second to restore the
default behavior.
For overnight sessions, provide explicit dates on both endpoints so the end date is unambiguous. BurrowTime does not silently advance an end time to the next day.
Add a message to describe work performed on a session. Messages stay separate from tags, so ticket-based reports continue to group time as before:
burrowtime start RAF +RAF-326 -m "Investigating migration issue"
burrowtime stop -m "Fixed migration mapping and updated tests"
burrowtime add --from "2026-10-27 10:00" --to "2026-10-27 11:00" RAF +RAF-326 -m "Completed QA testing"
burrowtime edit -1 -m "Updated description"
burrowtime log --all --json
burrowtime aggregate --from yesterday --show-messages
Messages are optional and remain separate from tags, so adding different work
descriptions to sessions with the same ticket does not change project or ticket
totals. Use burrowtime edit -1 -m "" to clear a message. In the TUI, Log
messages are visible by default; Report and Aggregate messages are hidden by
default. Press m to toggle visibility independently in each view. The CLI
aggregate output hides messages by default; --show-messages displays them
under their project and tag without changing totals. Untagged sessions show
their messages directly under the project.
The TUI shows messages beneath their sessions in Log. In Report, press m to
show messages beneath the matching project and ticket:
Use JSON or CSV when another program will consume the result:
burrowtime log --all --json | jq '.[0]'
burrowtime report --month --csv > august.csv
Session JSON and CSV logs include a message field/column when available.
BurrowTime MCP questions
How do I use BurrowTime with an MCP client?
Configure your agent to launch 'burrowtime mcp' over standard input and output using the provided JSON configuration.
Is my time data stored in the cloud?
No, BurrowTime is local-first and your time data stays in ordinary files on your machine.
Can I migrate from Watson to BurrowTime?
Yes, BurrowTime is Watson-compatible and can copy your existing Watson history on the first launch.
Does it support multiple timers at once?
Yes, you can start concurrent timers using the --concurrent flag or through the interactive TUI picker.