Ratchetfor FreeAgent, on macOS
Start the clock from the menu bar.
Ratchet starts and stops FreeAgent timers without a browser tab. While one is running the icon's rim and teeth turn green, so a glance tells you whether you are on the clock.
Try it
The icon in the menu bar above opens Ratchet's menu. This copy works, with invented clients, and nothing in it reaches FreeAgent.
What it does
- Start, stop, switch
- Start a timer on any task, or on the last one you tracked in a single click. Switching task moves the running timeslip rather than starting another, so it stays one continuous entry.
- Log time after the fact
- Book a duration and comment to any day you missed, from the same client, project and task picker.
- Correct mistakes
- Unbilled entries under Recent time entries open for editing. Invoiced ones are listed but locked, as FreeAgent locks them.
- Create as you go
- Add a client, project or task from inside the picker when the one you need does not exist yet.
- Nothing in between
- You sign in to FreeAgent in your browser and Ratchet talks to its API directly. There is no Ratchet server or account, and your sign-in tokens stay in the macOS Keychain.
Not released yet
Ratchet works end to end against FreeAgent, but there is no public build. The plan is a Homebrew cask from a personal tap, built by a release workflow on GitHub.
- Requires
- macOS 13 Ventura or later, and a FreeAgent account.
- Signing
- Not notarised by Apple, so the first launch needs Control-click, then Open. Later launches behave normally.
- Source
- Not public yet.
- Licence
- GNU GPL v3. Free software.
Still to do
Release
- Open
Publish the source
A public GitHub repository, to hold releases and the Homebrew tap.
- Partly done
Run the first release
The workflow is written: a version tag builds, bundles and zips the app into a GitHub release. It has never run, and still needs the production FreeAgent credentials added as repository secrets.
- Open
Host a Homebrew tap
A personal tap, since the official cask repository expects notarised apps. The cask is drafted and waits on a first release for its version, URL and checksum.
- Partly done
Confirm the quarantine strip
The cask clears macOS's quarantine flag on install so Gatekeeper's first-launch prompt is skipped. Unverified until there is a real release to test it on.
Features
- Open
An official FreeAgent listing
Ask FreeAgent about listing Ratchet as a recognised integration.
- Open
Offline tracking
Start a timer with no connection and sync it to FreeAgent once back online.
- Open
Several timers at once
FreeAgent's web app allows it. Ratchet models a single running timeslip, so this is a data-model change rather than a menu one.
- Partly done
Timers that run past midnight
FreeAgent appears to book the whole duration to the day the timer started. A "running since yesterday" note in the menu would make that visible.
- Open
Invoicing
Turn a client's unbilled timeslips into a FreeAgent invoice from the menu.
Known issues
- Open
A duplicate entry after a lost reply
If the connection drops after FreeAgent saves a logged entry but before it replies, retrying creates a second one. Timers recover by themselves; Log past time needs an idempotency key or a follow-up check.
- Blocked
Sign-in without a bundled secret
PKCE would let Ratchet drop its embedded client secret, but FreeAgent registers apps as confidential clients and rejects it. Waiting on FreeAgent.
Missing checksEach works today, but nothing would catch it breaking.
- Open
A timer FreeAgent reports as stopped
Starting a timer should fail loudly when FreeAgent's reply says it is not running.
- Open
Editing the running entry
The timer should keep its original start time when FreeAgent's reply leaves it out, rather than resetting the elapsed time.
- Open
A refresh that starts mid-change
A refresh beginning while a change is in flight must not overwrite that change when it lands.
Not planned: notarisation through a paid Apple Developer membership, and the Mac App Store. Homebrew is the target.