{"id":"2e4c8952-8db2-46ce-87b9-e233b561dce8","slug":"btrack","kind":"mcp","name":"btrack","summary":"One-line time tracker for developers that also logs your Claude Code, Codex and Hermes sessions. CLI + MCP.","owner":"tolgazorlu","repoUrl":"https://github.com/tolgazorlu/btrack","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-05-04T10:28:38.000Z","addedAt":"2026-10-21T08:49:03.787Z","logoUrl":"https://avatars.githubusercontent.com/u/44470351?u=1c2299897d24656ab26d6987504b20fc323565ec&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","utilities","productivity"],"tags":["cli","developer-tools","go","productivity","time-tracking","ai-agents","claude-code","codex"],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T08:52:16.532Z","sample":false,"url":"https://conduits.dev/tools/btrack","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# btrack\n\nA one-line time tracker for developers that also records what your AI coding agents did: Claude Code, Codex and Hermes sessions, the commits they produced and their estimated cost.\n\nEvery 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.\n\n[![Release](https://img.shields.io/github/v/release/tolgazorlu/btrack)](https://github.com/tolgazorlu/btrack/releases/latest)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Go](https://img.shields.io/badge/Go-1.26-00ADD8?logo=go)](go.mod)\n\n---\n\n## Install\n\n**macOS / Linux**\n```bash\nbrew install tolgazorlu/btrack/btrack\n```\n\n**Windows**\n```powershell\nirm https://raw.githubusercontent.com/tolgazorlu/btrack/main/install.ps1 | iex\n```\n\n**Go**\n```bash\ngo install github.com/tolgazorlu/btrack@latest\n```\n\nOr grab a binary from [Releases](https://github.com/tolgazorlu/btrack/releases/latest).\n\n---\n\n## Quick start\n\n```bash\nbtrack s \"fix login bug\"              # start tracking\nbtrack n \"found the issue\"            # add a note while working\nbtrack x -m \"fixed JWT clock skew\"   # stop and save\nbtrack h                              # see today's work\n```\n\n### Your AI agent sessions\n\n```bash\nbtrack sync                # import Claude Code, Codex and Hermes sessions from their local logs\nbtrack recap -w            # this week per project: your time, agent time, commits, estimated cost\nbtrack recap -m --md       # the same as markdown, for a standup or a client\n```\n\n`sync` is safe to repeat. Imported sessions stay separate from your hand-kept timesheet, so `btrack h`, `export` and `report` only bill what you recorded yourself; `recap` combines both without counting time twice.\n\n---\n\n## Commands\n\n### Core\n\n| Command | Alias | What it does |\n|---------|-------|--------------|\n| `btrack start \"task\"` | `s` | Start a session |\n| `btrack start \"task\" -p myapp` | `s -p` | Start in a project |\n| `btrack note \"text\"` | `n` | Add a note to the active session |\n| `btrack note \"text\" -i 42` | `n -i` | Add a note to a past session |\n| `btrack stop -m \"msg\"` | `x` | Stop and save |\n| `btrack stop --at \"2h ago\"` | `x --at` | Stop, backdated |\n| `btrack switch \"new task\"` | `sw` | Stop current, start new |\n| `btrack resume` | `r` | Continue last session |\n| `btrack add \"task\" --from 14:03 --to 15:10` | `a` | Record a finished session, no timer |\n\n### History\n\nAll history flows through `btrack h`:\n\n```bash\nbtrack h                  # today (default)\nbtrack h yesterday\nbtrack h 2026-05-01\nbtrack h -w               # this week\nbtrack h -m               # this month\nbtrack h -y               # this year\nbtrack h -n 20            # last 20 sessions as a table\nbtrack h -n 20 -v         # with notes\nbtrack h -l 5             # last 5 hours\nbtrack h -n 50 -p myapp   # filter by project\n```\n\n### Other views\n\n```bash\nbtrack w                  # live status TUI\n```\n\n---\n\n## Projects\n\nGroup sessions by project and filter history by it.\n\n```bash\nbtrack s \"fix auth\" -p myapp        # start session in a project\nbtrack projects                      # list all projects with total time\nbtrack h -n 50 -p myapp             # history filtered by project\nbtrack config project myapp rate 150 # record an hourly rate\n```\n\n### .btrack file\n\nDrop a `.btrack` file in a repo root to set per-project defaults. `btrack s` picks it up automatically.\n\n```bash\nbtrack init   # interactive wizard — creates .btrack for you\n```\n\n```ini\n# .btrack\nproject     = myapp\ntask_prefix = [myapp]\ndaily_hours = 6\n```\n\n---\n\n## Editing sessions\n\n```bash\nbtrack h -n 20                        # find session IDs\nbtrack edit 42 -t \"new task name\"\nbtrack edit 42 --start 09:00 --end 17:30\nbtrack edit 42 -p myapp -m \"done #bugfix\"\n```\n\n---\n\n## Use it from an AI agent\n\nTwo integrations; use either or both.\n\n- **Skill**: teaches the agent to log its own work sessions with btrack (below).\n- **MCP**: gives the agent the ledger itself, through the tools `recap`, `log_work`, `list_sessions`, `unlogged_days`, `sync` and `projects`:\n\n  ```bash\n  claude mcp add btrack -- btrack mcp\n  codex mcp add btrack -- btrack mcp\n  ```\n\n  or in any MCP client: `{\"mcpServers\": {\"btrack\": {\"command\": \"btrack\", \"args\": [\"mcp\"]}}}`\n\nEvery command also takes `--json`.\n\n### Skill\n\nThe bundled `btrack` skill teaches Claude Code (and other CLI agents) to track your sessions on its own. The default flow is clock mode: the agent notes the wall-clock time when work starts, and records the finished session with `btrack add --from --to` when it's done — btrack computes the duration, so no timer runs while the AI works. Timer mode (`btrack s` / `x`) stays available for live terminal sessions.\n\n**Install — pick one:**\n\n```bash\nbtrack skill install                 # writes ~/.claude/skills/btrack/, no Node required\n```\n\n```bash\nnpx skills add tolgazorlu/btrack     # via skills.sh — same destination\n```\n\nBoth write the same files: `SKILL.md`, `README.md`, `metadata.json`, plus a `references/` directory with deep-dive docs. Fully quit and reopen Claude Code so it loads the skill.\n\n**Other skill commands:**\n\n```bash\nbtrack skill print       # dump SKILL.md to stdout\nbtrack skill path        # print the install path\nbtrack skill install --force   # overwrite a customized skill on upgrade\n```\n\nThe skill source lives in [`skills/btrack/`](skills/btrack/).\n\n---\n\n## Configuration\n\n```bash\nbtrack config                # show all settings\nbtrack config hours 6        # daily hour target\nbtrack config idle 15        # auto-stop after 15 min idle (0 = off)\nbtrack config max-hours 12   # hard cap on one session (0 = off)\n```\n\nConfig file: `~/.config/btrack/config.yaml`. Sessions are stored in a local SQLite database.\n\n---\n\n## Export\n\n```bash\nbtrack export                              # CSV to stdout\nbtrack export --format json --out data.json\nbtrack export --days 30 --out may.csv\nbtrack export -p myclient --days 30        # one project, one month\n```\n\n---\n\n## Client reports\n\n`btrack report` builds the document you hand a client when you invoice them:\nwhat you committed, and how long it took. Two parts, one HTML file.\n\n```bash\nbtrack report myclient --from 21.08 --to 16.09   # a billing period\nbtrack report myclient -m                        # this month\nbtrack report myclient --from 01.09 --open       # open it when done\n```\n\nPart 1 reads the git history of the repository you run it in: every non-merge\ncommit, grouped by day, tagged feat/fix/chore/revert, with the pull request\nthat merged it. Part 2 reads your btrack sessions for the same range, with\nper-day and grand totals.\n\nThe file lands in your home directory. `--out` puts it elsewhere, `--repo`\nscans a repository other than the current directory, and `--client` sets the\nname printed on the masthead.\n\n### Backfilling hours you tracked elsewhere\n\nIf your hours live in a stopwatch app or a spreadsheet, import them once and\nthe report can build itself from then on. The file is one record per line,\ntab- or comma-separated — date, duration, description:\n\n```\n21.08.2026    1.00.46     Request triage + reservation editing + test + deploy\n24.08.2026    24.09.27    Pattern sort + test + deploy\n24.08.2026    15m43s      Mobile app bug review [no commit]\n```\n\n```bash\nbtrack import hours.tsv -p myclient --dry-run   # show what would happen\nbtrack import hours.tsv -p myclient             # write it\n```\n\nDurations accept the forms people actually write by hand: `1.00.46`,\n`24.09.27`, `1:09:20`, `45m29s`, `1 sa 9 dk`, `0.75h`. A trailing `[note]` in\nthe description becomes a chip beside the entry in the report. Always run\n`--dry-run` first.\n\n---\n\n## Data and privacy\n\nEverything stays on your machine, in one SQLite file: `~/Library/Application Support/btrack/` on macOS, `~/.local/share/btrack/` on Linux, `%LOCALAPPDATA%\\btrack\\` on Windows (`BTRACK_DB` overrides the path). `btrack sync` only reads the session logs your agents already keep locally. The only network call is the update check in `btrack w`, a request to the GitHub releases API. No telemetry.\n\n---\n\n## Build from source\n\n```bash\ngit clone https://github.com/tolgazorlu/btrack.git\ncd btrack\ngo build -o btrack .\n```\n\n---\n\n## Related\n\nHomebrew tap: [tolgazorlu/homebrew-btrack](https://github.com/tolgazorlu/homebrew-btrack)\n\n---\n\n## License\n\nMIT\n"}