Work Timer

Current version: 1.3.32

A zero-cost, open-source work timer and billing tool built for solo contractors and freelancers. Control it with natural language through any MCP-compatible AI assistant (Claude, Cursor, etc.) or via the command line.

Features

• Natural language control — "Start a timer for Project Alpha", "How much time on Client X this month?"
• MCP server — Works with Claude Desktop, ChatGPT, GitHub Copilot, Cursor, and any MCP-compatible client
• Expanded CLI integrations — Auto-installer supports Claude Code, OpenAI Codex CLI, and Google Gemini CLI command-based MCP registration
• Built-in MCP help — work_timer_help explains capabilities, workflows, and example usage for LLMs/users
• MCP auto-installer — Programmatically detects and patches supported local MCP client configs with backup + dry-run support
• CLI — Full command-line interface for quick manual use
• Built-in maintenance — Includes work-timer update, work-timer uninstall, and update-available prompts
• Safe destructive operations — Confirmation flow in CLI and dry_run + confirm_phrase safety gates in MCP for destructive actions
• Session time correction — Adjust start/end times in local time while storing UTC safely
• Local-time UX — Displays and date filters are local-time aware while database storage remains UTC
• Overlapping timers — Bill multiple clients simultaneously
• Flexible billing — Per-project rates, currencies, and minimum billing blocks with global defaults
• Invoice tracking — Mark sessions as invoiced and paid with reference numbers
• Export — CSV, Excel (XLSX), and accounting-specific presets (QuickBooks, Xero, FreshBooks, Sage, MYOB)
• Modern XLSX export — Excel exports use a smaller maintained writer dependency instead of the older exceljs stack
• Cloud sync — Turso database means your data is accessible from any device
• Free — Turso free tier (9GB, 500M reads/mo) is more than enough for any solo practice

Quick Start

1. Install

Windows PowerShell (one line):

irm https://raw.githubusercontent.com/JoelBondoux/Work-Timer/master/install.ps1 | iex

macOS / Linux (one line):

curl -fsSL https://raw.githubusercontent.com/JoelBondoux/Work-Timer/master/install.sh | bash

These scripts auto-detect whether your local Work-Timer folder already exists and then clone or update, install dependencies, build, and run npm link.

For production pinning, replace master in the URL with a release tag such as v1.3.32.

Faster branch-testing options:

• Skip build: set WORK_TIMER_SKIP_BUILD=1
• Skip global relink: set WORK_TIMER_SKIP_LINK=1
• Existing valid ~/Work-Timer installs are updated in place
• If the target folder exists but is not a Work-Timer install, it is moved to a timestamped backup and installation continues in the requested folder
• If an existing Work-Timer install has uncommitted changes, installer stops by default; generated dist/-only changes are ignored, and you can still set WORK_TIMER_ALLOW_DIRTY=1 when you intentionally want to proceed
• Dirty-state errors include the active branch and a preview of blocking files to speed up cleanup
• When only generated tracked files in dist/ are changed, installer now resets dist/ before pull to avoid fast-forward conflicts during update
• If the installed version already matches the requested version, installer asks whether to repair (reinstall deps/rebuild/relink) or cancel
• In non-interactive environments, set WORK_TIMER_REPAIR_MODE=repair to force repair, or WORK_TIMER_REPAIR_MODE=cancel to skip

Windows users: npm link may require adding npm's global bin to your PATH and setting PowerShell's execution policy. See the Setup Guide for details.

2. Set Up Database

Create a free Turso account and set up a database:

Via web dashboard (recommended for Windows): Go to app.turso.tech, create a database, and copy the database URL and auth token from the database settings.

Via CLI (macOS / Linux):

curl -sSfL https://get.tur.so/install.sh | bash
turso auth login
turso db create work-timer
turso db show work-timer --url       # Copy this
turso db tokens create work-timer    # Copy this

Run the setup wizard:

work-timer setup

Keep Work-Timer and the MCP server up to date from GitHub:

work-timer update

If you need to bootstrap a broken older install manually, use the same tarball install path as work-timer update: (this also helps when npm PATH resolution is inconsistent in older global installs)

npm install -g https://codeload.github.com/JoelBondoux/Work-Timer/tar.gz/refs/heads/master

Optional: auto-register Work-Timer in detected local MCP clients:

work-timer mcp install --dry-run
work-timer mcp install --create-missing

Or set environment variables:

export TURSO_DATABASE_URL="libsql://your-db-url.turso.io"
export TURSO_AUTH_TOKEN="your-token"

3. Start Tracking

Via CLI:

work-timer start "Client Alpha"
# ... work for a while ...
work-timer stop
work-timer query "Client Alpha"

Via AI assistant (MCP):

Add to your MCP client configuration (Claude Desktop, ChatGPT, GitHub Copilot, Cursor — see Setup Guide for each):

{
  "mcpServers": {
    "work-timer": {
      "command": "node",
      "args": ["/path/to/Work-Timer/dist/mcp/server.js"]
    }
  }
}

Then just talk naturally:

"Start a timer for the Website Redesign project" "Pause the timer" "How much time have I spent on Website Redesign this week?" "Export my billing for January as Excel" "How does Work-Timer work?"

Documentation

Guide	Description
Setup Guide	Full installation and configuration instructions
CLI Reference	Every CLI command with examples
MCP Tools Reference	Every MCP tool with parameters and example prompts
Configuration	Global defaults, project settings, environment variables
Billing Logic	How duration, rounding, and amounts are calculated
Export Guide	CSV and XLSX export formats and accounting software import
Invoicing Guide	Tracking invoices and payments
Roadmap	Planned future enhancements and priorities
Contributing	Developer setup, architecture, and PR guidelines

How It Works

Work-Timer stores all data in a Turso cloud database (a hosted SQLite-compatible service). This means:

• Your time data syncs across all your devices automatically
• No server to run or maintain
• The free tier is generous enough for any solo contractor
• All timestamps are stored in UTC for consistency

Both the MCP server and CLI use the same core logic, so behavior is identical regardless of how you interact with Work-Timer.

Architecture

src/
  types.ts          # Shared TypeScript interfaces
  db/
    schema.ts       # Database schema and migrations
    client.ts       # Turso client management
  core/
    timer.ts        # Start/stop/pause/resume logic
    projects.ts     # Project CRUD operations
    billing.ts      # Duration and billing calculations
    settings.ts     # Global default settings
    sessions.ts     # Session queries and invoice marking
    export.ts       # CSV, XLSX, and accounting preset export
    presets.ts      # Accounting software export presets
    format.ts       # Text formatting for output
  mcp/
    server.ts       # MCP server with 21 tool definitions
  cli/
    index.ts        # CLI entry point with Commander.js

License

MIT