HourPilot

The missing planning layer for Toggl.

A Chrome extension that adds weekly planning, planned-vs-actual tracking, and capacity visibility on top of your existing Toggl workflow. Local-first, no backend, no account.

---

Install

Option A — Quick install (no Node required)

If hourpilot.zip exists in this folder (produced by npm run build && npm run zip):

1. Extract hourpilot.zip into a folder
2. Open Chrome → chrome://extensions
3. Toggle Developer mode on (top right)
4. Click Load unpacked → select the extracted folder
5. Pin the extension to your toolbar

If the zip isn't there yet, use Option B first to generate it.

Option B — Build from source

Requires Node 18+. Works on Windows without any C++ build tools — Vite + @crxjs/vite-plugin are pure JS.

npm install
npm run build

This produces a dist/ folder. Load that folder via chrome://extensions → Load unpacked.

For development with hot reload:

npm run dev

Then load the dist/ folder (Vite will keep it updated).

To regenerate the pre-built zip after a build:

npm run zip

---

First-time setup

1. Click the HourPilot icon in your toolbar
2. Paste your Toggl API token (find it at track.toggl.com/profile → scroll to API token)
3. Set your weekly capacity (e.g. 40)
4. Done — you're in

---

Daily use

Plan tab — Add projects from Toggl and assign planned hours for the week. Use the + / − buttons (0.5h steps). The footer shows total planned vs your capacity.

Vs Actual tab — See planned vs tracked hours side-by-side, with delta badges. Projects you've tracked but didn't plan show up as "untracked."

Capacity tab — Donut shows weekly utilization. Daily bars show how your tracked time distributes Monday → Sunday.

Week navigation — Arrows in the header, or "Today" to jump back to the current week.

Running timer — A green pill in the header shows your currently running Toggl timer (updated when you open the popup).

Settings — Gear icon. Change capacity, refresh data from Toggl, or disconnect.

---

Architecture

src/
├── App.tsx              # state orchestration, screen switching
├── popup.tsx            # entry point
├── popup.html
├── background.ts        # MV3 service worker — 5min cache invalidation alarm
├── lib/
│   ├── toggl.ts         # Toggl API v9 client
│   ├── storage.ts       # chrome.storage wrapper (sync + local cache)
│   ├── data.ts          # loaders + computeActuals derivation
│   └── time.ts          # ISO week math, formatters
├── tabs/
│   ├── PlanTab.tsx
│   ├── VsActualTab.tsx
│   └── CapacityTab.tsx
├── components/
│   ├── Header.tsx
│   ├── WeekNav.tsx      # week navigator + tab bar
│   ├── Onboarding.tsx
│   ├── Settings.tsx
│   ├── ErrorBoundary.tsx
│   └── Icons.tsx        # inline SVG icon set
├── styles/global.css    # dark operational theme
└── types/index.ts

Data flow

1. Settings live in chrome.storage.sync (102KB limit, plenty for tokens + plans)
2. Week plans are keyed plan:2026-W20 in sync storage
3. API responses (projects, clients, time entries) are cached in chrome.storage.local with TTLs:
   • Projects/clients: 1 hour
   • Time entries: 5 minutes
4. The background worker clears entry caches every 5 minutes so the next popup open fetches fresh data
5. Toggl is read-only — HourPilot never writes to your Toggl account

Why these choices

• Vite + CRXJS — pure JS toolchain. No sharp, no node-gyp, no Visual Studio Build Tools needed on Windows.
• Hand-rolled SVG charts — the donut and day bars are ~80 lines. Pulling in Recharts (~100KB) for this was overkill.
• chrome.storage.sync for plans — plans roam across your Chrome installs automatically.
• Local-first — there is no server. There never will be (for V1).

---

Toggl API notes

• Auth: HTTP Basic, ${token}:api_token base64-encoded
• Endpoints: /me, /me/projects, /workspaces/{id}/clients, /me/time_entries
• Rate limits: cached aggressively (5min for entries, 1hr for projects)
• Running timers: duration < 0 and stop === null — elapsed time computed from start

---

What this is not

• ❌ A task manager
• ❌ A team / multi-user app
• ❌ A calendar integration
• ❌ An invoicing tool
• ❌ AI anything

Every feature in HourPilot earns its place by serving the core loop: plan the week → track normally in Toggl → see how you actually spent it.

---

Troubleshooting

npm install fails on Windows. Make sure you're on Node 18 or newer (node --version). All dependencies are pure JavaScript — there are no sharp, canvas, or node-gyp packages. If you see errors mentioning "C++", "Python", or "Visual Studio Build Tools", something is wrong with your Node setup, not with HourPilot.

The popup is blank. Open chrome://extensions, find HourPilot, click "service worker" to see background errors, or right-click the popup → Inspect to see the console.

"Invalid API token" right after setup. Your token may have whitespace around it. Re-copy it from track.toggl.com/profile — the input strips whitespace but copy/paste managers sometimes mangle long strings.

Projects don't appear. They must be marked Active in Toggl. Archived projects are excluded.

Stale data. Click the refresh icon in the header, or open Settings → Data → Refresh from Toggl.

---

License

MIT