We use Harvest to track our time. As a team lead, I will often have multiple projects or tasks that I need to log. Between interviewing, helping with sales, 1:1s, and sometimes work on multiple projects, I can log up to 7 or so different things in a week, often switching between them several times a day.

The Harvest app for OS X lacks good keyboard shortcuts for quickly switching tasks, so I set out to build my own.

Animation of keyboard shortcut

The end result is that I can hit ;+h (also known as Hyper-H with my setup, more on this later) followed by another letter to switch to a Harvest task. If the task was already started today, it will resume it, otherwise it will start a new task.

To do so, I made use of the very handy Keyboard Maestro, the hcl gem and (optionally) Karabiner.


  1. Install Keyboard Maestro. It’s not free, but it has a long trial, and it is well worth the money.

  2. Install the hcl gem. I use RVM, so, I installed the gem to my system ruby in order to simplify things.

# If not using RVM:
$ sudo gem install hcl

# If using RVM:
$ rvmsudo rvm system do gem install hcl 
$ rvm use system
  1. Add these scripts somewhere. They do not necessarily need to be in your path because you will specify the full path within Keyboard Maestro.

In bin/hcl-start:

#!/usr/bin/env sh
# stop first because resume isn't idempotent
/usr/bin/hcl stop
/usr/bin/hcl resume $1 $2 || /usr/bin/hcl start $1 $2

In bin/hcl-stop:

#!/usr/bin/env sh
/usr/bin/hcl stop
  1. List your tasks with hcl. This will require you to login to your Harvest account.
    $ hcl tasks
  1. Make note of the two numbers by the tasks you will want to add keys for.

  2. Using the Keyboard Maestro Editor, create a Group called “Harvest”.

  3. Add a new Macro. Give it a name after one of your tasks, but prefix it with a single capital letter you’d like to be your hotkey for it. Example: “I - Internal Meetings”.

Start Macro in Keyboard Maestro

  1. Assign a hotkey. You will use the same hotkey for all of your macros. One of the great features of Keyboard Maestro is that it will display a menu if multiple things have the same hotkey and allow you to hit a single letter to choose which one you want. I use ^⌥⇧⌘H, though I have my ; key bound to ^⌥⇧⌘ (Hyper), more on that later.

  2. Add an “Execute Shell Script” action to your macro. Set it to “Execute text script” and “display results briefly”. Call your hcl-start script, using the project id and task id that correspond to this task:

    ~/bin/hcl-start <project-id> <task-id>
  1. Repeat for your other tasks.

  2. Add a stop task, I use “Z - Stop Timer”. Everything will be the same, but you’ll call hcl-stop instead:


Stop Macro in Keyboard Maestro

  1. Try it out. Hit your key, followed by the letter of the task you want to start. You should see a notification after a second or two (the harvest API isn’t exactly fast).

Bonus Material - Hyper Key!

I’m sure you’ve all thought, ok, I have command, ctrl, option and shift. That is not nearly enough modifier keys, Amirite?! I find it’s very useful to have a modifier key that no other apps can use for global hotkeys. Hyper fits the bill. There is a great article on many things keyboard related, including Hyper here, so I will spare you the details and cut right to the chase.

I use ; as my Hyper key, but only when it is held. If I just tap ; it comes out as a ;. I do this using another piece of excellent keyboard customization software, Karabiner. Install it, add this to your private.xml, click “Reload XML”, and check the new box it added.

<?xml version="1.0"?>
    <name>Remap ; to Hyper when held down, ; when typed normally</name>
      OS X doesn't have a Hyper. This maps semicolon to
      Control + Shift + Option + Command.


        ModifierFlag::OPTION_L | ModifierFlag::SHIFT_L | ModifierFlag::CONTROL_L,

    <!-- ; followed by space is difficult to type w/o triggering hyper,
         this works around it -->
        ModifierFlag::COMMAND_L | ModifierFlag::OPTION_L | ModifierFlag::SHIFT_L | ModifierFlag::CONTROL_L,
        KeyCode::SEMICOLON, KeyCode::SPACE