Work-Timer

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