Time Tracker
VS Code extension for consulting time tracking and local PDF invoicing. Data is stored locally in SQLite; optional cross-machine sync uses VS Code Settings Sync (no separate cloud account).
Features
- Timer — Start/stop from the status bar or command palette; auto-tags client/project from your workspace folder mapping
- Manual entries — Add, edit, or delete time before invoicing
- Clients & projects — Per-client hourly rates, billing addresses, customer IDs
- Weekly invoices — Preview lines, exclude entries, generate PDF invoices with a professional consulting layout
- Local storage — Database and PDFs in VS Code global storage (
~/.config/Code/User/globalStorage/kdcllc.agentic-ai-time-tracker/ on Linux)
Quick start
- Install the extension (or press F5 to run from source).
- Open a client workspace folder in VS Code.
- When prompted, Link workspace to a client and project.
- Run Time Tracker: Start Timer (status bar shows elapsed time; click to stop).
- At week end, run Time Tracker: Generate Invoice.
Commands
| Command |
Description |
| Time Tracker: Start Timer |
Begin tracking |
| Time Tracker: Stop Timer |
Save elapsed time as an entry |
| Time Tracker: Add Manual Entry |
Log hours without the timer |
| Time Tracker: Generate Invoice |
Choose date range (presets or custom), preview lines, generate PDF |
| Time Tracker: Link Workspace to Client |
Map folder → client/project |
| Time Tracker: Add / Edit Client |
Manage billing clients (name, address, Customer ID for invoice header) |
| Time Tracker: Edit Company Settings |
Your issuer name, address, email, payment footer on PDFs |
| Time Tracker: Set Company Logo |
Pick a PNG/JPEG logo for invoice PDFs |
| Time Tracker: Sync Now |
Push local data then pull newer remote snapshot |
| Time Tracker: Show Last Sync Time |
Display last Settings Sync timestamp |
Cross-machine sync (VS Code Settings Sync)
Sync clients, projects, time entries, invoice metadata, and company DB settings across machines signed into the same VS Code / Cursor account. Invoice PDF files are not synced (regenerate locally if needed).
Setup
- Manage gear → Backup and Sync Settings (or Accounts menu) → sign in with Microsoft or GitHub.
- Ensure Settings and Extensions are enabled in sync (install Time Tracker on each machine).
- Keep
timeTracker.sync.enabled set to true (default).
- On a second machine, reload the window after sync completes — data appears on startup.
What syncs automatically
| Data |
Mechanism |
timeTracker.company.* settings |
VS Code Settings Sync |
| Clients, projects, entries, invoices |
Extension snapshot via globalState.setKeysForSync |
| Workspace mappings (folder name only) |
Included in snapshot |
| Workspace mappings (full path) |
Per-machine only |
| Invoice PDF files |
Local only |
Troubleshooting
- Run Time Tracker: Sync Now after large imports.
- Check Output → Time Tracker for
Sync on startup: / Sync: pushed messages.
- Use Settings Sync: Show Synced Data to verify
timeTracker.syncPayload exists.
- Re-run Set Company Logo on each machine (logo file paths are machine-specific).
Settings
| Setting |
Default |
Description |
timeTracker.company.name |
Acme Consulting LLC |
Issuer name on invoice (left header); fictional example |
timeTracker.company.addressLine1 |
123 Market Street |
Issuer street address |
timeTracker.company.addressLine2 |
Springfield, IL 62701 |
Issuer city, state, zip |
timeTracker.company.email |
billing@acme-consulting.example |
Issuer email on invoice |
timeTracker.company.paymentInstructions |
(empty) |
Payment footer text |
timeTracker.company.logoPath |
(empty) |
PNG/JPEG path on invoice header (~ supported) |
timeTracker.weekStartsOn |
monday |
Week boundary for invoices |
timeTracker.defaultWorkWeek |
previous |
Which week preset appears first when generating an invoice |
timeTracker.roundingMinutes |
0 |
Round stopped timer (e.g. 6) |
timeTracker.invoiceExportPath |
(empty) |
Also copy PDFs here |
timeTracker.sync.enabled |
true |
Sync data via VS Code Settings Sync |
Architecture
The extension follows SOLID-oriented layering:
| Layer |
Role |
core/ports |
Interfaces for repositories, PDF, storage, config, and UI prompts (DIP, ISP) |
db/repositories |
SQLite persistence implementations |
infrastructure |
VS Code, filesystem, and pdf-lib adapters |
application |
Use-case services (timer, workspace, clients, invoicing) |
presentation |
Command registration |
composition |
Dependency wiring (createContainer) |
Development
npm install
npm run compile
# Press F5 in VS Code to launch Extension Development Host
npm test
Build a .vsix for manual install or upload
The marketplace icon lives at src/images/kdcllc-icon.png (128×128 PNG). Each compile / package copies it to media/icon.png for the VSIX (.vscodeignore excludes src/).
npm run package
npm run vsce-package
This produces agentic-ai-time-tracker-1.0.0.vsix in the project root. Install locally with Extensions → … → Install from VSIX, or upload that file to the Marketplace.
Marketplace upload checklist
| Requirement |
Value in package.json |
| Publisher (must match your Marketplace account) |
kdcllc |
| Extension ID (must be globally unique) |
agentic-ai-time-tracker — not time-tracker (already taken) |
Upload agentic-ai-time-tracker-1.0.0.vsix, not an older time-tracker-*.vsix from a previous build.
Publish to VS Code Marketplace
- Create a publisher (e.g.
kdcllc).
- Create an Azure DevOps PAT with Marketplace → Manage scope.
npx vsce login kdcllcnpm run package && npm run vsce-package then upload the .vsix, or npx vsce publish
Ensure publisher in package.json matches your Marketplace publisher id.
Privacy
This extension does not call its own servers. When Settings Sync is enabled, VS Code syncs registered settings and extension state to your Microsoft/GitHub account using the built-in sync service. PDFs remain on each machine unless you copy them yourself.
License
MIT — Copyright (c) 2026 King David Consulting LLC
