Every time tracker I tried wanted me to open a browser, log in, pick a workspace, and click through a dashboard. I just wanted to type one line and get back to work.
macOS / Linux
brew install tolgazorlu/btrack/btrackWindows
irm https://raw.githubusercontent.com/tolgazorlu/btrack/main/install.ps1 | iexGo
go install github.com/tolgazorlu/btrack@latestOr grab a binary from Releases.
btrack s "fix login bug" # start tracking
btrack n "found the issue" # add a note while working
btrack x -m "fixed JWT clock skew" # stop and save
btrack h # see today's work| Command | Alias | What it does |
|---|---|---|
btrack start "task" |
s |
Start a session |
btrack start "task" -p myapp |
s -p |
Start in a project |
btrack note "text" |
n |
Add a note to the active session |
btrack note "text" -i 42 |
n -i |
Add a note to a past session |
btrack stop -m "msg" |
x |
Stop and save |
btrack switch "new task" |
sw |
Stop current, start new |
btrack resume |
r |
Continue last session |
btrack break |
— | Start a break |
All history flows through btrack h:
btrack h # today (default)
btrack h yesterday
btrack h 2026-05-01
btrack h -w # this week
btrack h -m # this month
btrack h -y # this year
btrack h -n 20 # last 20 sessions as a table
btrack h -n 20 -v # with notes
btrack h -l 5 # last 5 hours
btrack h -n 50 -p myapp # filter by projectbtrack w # live status TUI
btrack stats # today / week / month snapshot
btrack streak # working-day streak + 30-day calendar
btrack search "JWT" # full-text search
btrack tag #bugfix # filter by tag
btrack shipped # git commits that landed during your sessionsGenerate a standup from your tracked sessions with AI. Defaults to yesterday — run it in the morning before your standup meeting.
btrack standup # yesterday (default)
btrack standup --today # today's sessions so far
btrack standup --days 3 # last 3 daysOutput format:
Yesterday:
• Fixed JWT auth bug (2h)
• Wrote unit tests for auth module (1h)
Today:
• PR review, deploy to staging
Blockers:
• None
Requires an AI key: btrack ai setup
Group sessions by project, filter history, generate invoices.
btrack s "fix auth" -p myapp # start session in a project
btrack projects # list all projects with total time
btrack h -n 50 -p myapp # history filtered by project
btrack config project myapp rate 150 # set hourly rateDrop a .btrack file in a repo root to set per-project defaults. btrack s picks it up automatically.
btrack init # interactive wizard — creates .btrack for you# .btrack
project = myapp
task_prefix = [myapp]
daily_hours = 6btrack invoice -p myapp -r 150 # current month, stdout
btrack invoice -p myapp -r 150 --month 2026-04
btrack invoice -p myapp -r 150 --round # round to 15 min
btrack invoice -p myapp --out invoice.txt # save to filebtrack h -n 20 # find session IDs
btrack edit 42 -t "new task name"
btrack edit 42 --start 09:00 --end 17:30
btrack edit 42 -p myapp -m "done #bugfix"Show the active session in your terminal prompt. Outputs nothing when idle.
btrack shell zsh # print ready-to-paste zsh snippet
btrack shell bash # print ready-to-paste bash snippet
btrack shell fish # print ready-to-paste fish snippetZsh — add to ~/.zshrc:
btrack_prompt() { btrack prompt 2>/dev/null; }
RPROMPT='$(btrack_prompt)'Bash — add to ~/.bashrc:
btrack_prompt() {
local s=$(btrack prompt 2>/dev/null)
[ -n "$s" ] && echo " $s"
}
PS1='\u@\h \w$(btrack_prompt) \$ 'Fish — add to ~/.config/fish/functions/fish_right_prompt.fish:
function fish_right_prompt
btrack prompt 2>/dev/null
endStarship — add to ~/.config/starship.toml:
[custom.btrack]
command = "btrack prompt --format starship"
when = "btrack prompt"
format = "[$output]($style) "
style = "blue"Result: fix login bug · 23m on the right side of your prompt.
btrack ai setup # configure OpenAI, Claude, or Gemini
btrack ai # interactive chat with session context
btrack ai sum # standup from today's sessions
btrack ai sum --days 3
btrack ai ins # productivity dashboardbtrack mcp runs btrack as a Model Context Protocol stdio server. Any MCP-aware client can call its tools to read your sessions or start/stop tracking inside a chat — Claude Code, Claude Desktop, Cursor, Gemini CLI, and Continue all work.
Tools exposed:
btrack_status active session + recent log notes
btrack_start start a new session
btrack_stop stop the active session
btrack_switch atomic stop+start
btrack_resume resume the last task
btrack_log_note attach a checkpoint note
btrack_history sessions in a window (today/yesterday/week/month/date:.../last_n:N)
btrack_search full-text search across tasks and messages
btrack_list_projects projects with cumulative time
btrack_get_session one session with all its notes
claude mcp add btrack -- btrack mcpAdd to the MCP config (~/.cursor/mcp.json, claude_desktop_config.json, etc.):
{
"mcpServers": {
"btrack": {
"command": "btrack",
"args": ["mcp"]
}
}
}In ~/.gemini/settings.json:
{
"mcpServers": {
"btrack": {
"command": "btrack",
"args": ["mcp"]
}
}
}If the stdio launch isn't working (PATH issues, sandboxing, etc.), run the HTTP server yourself and register the URL instead:
btrack mcp --http # 127.0.0.1:8765, path /mcpclaude mcp add --transport http btrack http://127.0.0.1:8765/mcpOnce registered, ask the assistant things like "What am I tracking right now?", "What did I work on this week?", or "Start a session called 'fix flaky CI'" — it will call the right tool itself. The MCP server shares state with the daemon, so anything an AI starts shows up immediately in btrack w and vice versa.
The MCP gives Claude the ability to call btrack_* tools. The bundled btrack skill teaches it to use them automatically — auto-start a session before coding, drop checkpoint notes for non-obvious findings, and stop the session right before git commit so btrack shipped lines commits up with sessions.
Install — pick one:
btrack skill install # writes ~/.claude/skills/btrack/, no Node requirednpx skills add tolgazorlu/btrack # via skills.sh — same destinationBoth write the same files: SKILL.md, README.md, metadata.json, scripts/setup.sh, plus a references/ directory with deep-dive docs. Then register the MCP and restart Claude Code:
claude mcp add btrack -- btrack mcp
# fully quit and reopen Claude CodeOr run the bundled setup script which does the MCP step for you:
~/.claude/skills/btrack/scripts/setup.shOther skill commands:
btrack skill print # dump SKILL.md to stdout
btrack skill path # print the install path
btrack skill install --force # overwrite a customized skill on upgradeMigrating from btrack-tracker (pre-v0.6.7): the skill was renamed from btrack-tracker to btrack. Remove the old install before reinstalling:
rm -rf ~/.claude/skills/btrack-tracker
btrack skill installThe skill source lives in skills/btrack/ — see docs/skills.md for the contributor guide on adding new skills.
Push sessions to Google Calendar after stopping.
Setup (once):
- Google Cloud Console → new project → enable Calendar API
- Credentials → OAuth 2.0 Client ID → Desktop app
- Copy the client ID and secret
btrack gcal connect --client-id <id> --client-secret <secret>
btrack gcal auto-sync on # push automatically after every stopOther commands:
btrack gcal status # check connection
btrack gcal sync # push last 7 days
btrack gcal sync --days 30
btrack gcal push 42 # push a specific sessionbtrack pomo "write tests" # 25/5 default
btrack pomo "deep work" --work 45 --break 10Each interval creates a regular session tagged #pomo. Press q to stop early.
btrack github connect # connect your account
btrack github sync # import today's commits as sessionsOnce connected, btrack standup and btrack ai sum include real commits and PRs.
btrack config # show all settings
btrack config hours 6 # daily hour target
btrack config idle 15 # auto-stop after 15 min idle (0 = off)Config file: ~/.config/btrack/config.yaml
btrack export # CSV to stdout
btrack export --format json --out data.json
btrack export --days 30 --out may.csvgit clone https://github.com/tolgazorlu/btrack.git
cd btrack
go build -o btrack .MIT