Harvest

Drive the user's Harvest timers from the terminal through the harvest MCP server. The hard part is choosing where time goes: a Harvest project (one of many under the client, each with a code such as PROJ-14) and a task inside it. The Jira key goes in the entry's notes, followed by - reviewing PR on a review session.

Hard rules

• Only the user's own time. Never pass user_id; never read, start or stop another person's entries.
• Jira is read-only. Harvest writes are limited to start_timer, stop_timer and log_time. Hours and notes of existing entries are never edited here.
• Every write is preceded by a one-line statement of what will be written: <client> / <project> [<code>] · <task> · "<notes>", plus hours and date for log.
• Before the first Harvest call, check the harvest tools are present. If they are not, stop and print claude mcp add --transport http -s user harvest https://api.harvestapp.com/mcp, then /mcp to sign in.

Account facts (from get_account_settings, re-check if a write is rejected): whether notes are optional, whether hours are rounded, whether timers store durations only (a clock range on log then becomes hours, with no start or end time kept), and whether approval is required so entries show as unsubmitted until the user submits their timesheet. Read them once per session.

Elapsed time on a running timer is hours plus the time since timer_started_at; the API's hours field only holds what was saved before the timer last started, so it reads 0.0 for a fresh timer however long it has run. timer_started_at is UTC; convert to local time before showing it. Show elapsed, never the raw field.

Modes

Resolve the ticket

Used by start and log. Find the key and fetch the ticket per references/ticket.md. Free text means ticketless work: it becomes the notes and the project comes from the candidate list (see the ladder's last rung). Keep the summary for the confirmation line, the issue type and the review flag for the task choice, and the epic for the ladder.

Resolve the project and task

Follow references/project-ladder.md. It yields a project with a strength (strong or weak), a task, and possibly runners-up. The map from Jira project key to Harvest client lives in references/harvest-map.md; past picks live in references/learned.md.

start

1. Resolve the ticket, project and task.
2. get_running_timer.
   • Same ticket already running (notes contain the key): say so, with elapsed hours, and finish.
   • Running and spent_at is today: note project, notes and hours; it will be switched. Harvest stops it when the new one starts.
   • Running and spent_at is an earlier day: stop here, show it, ask whether to stop_timer it first. That entry likely needs fixing in Harvest by hand.
3. Confirm or go:
   • Ticket from argument or branch and project strong → start without asking.
   • Anything else → present the recommendation, the runners-up, and the client's full project list per the ladder's listing rules, and ask with AskUserQuestion (recommendation first, then runners-up, then "pick from the list").
4. start_timer with project_id, task_id, notes = the key, plus - reviewing PR on a review (PROJ-193 - reviewing PR); free text as given.
5. Report the one-line statement and, if a timer was switched, what it was and its hours.
6. If the user chose something the ladder did not recommend, append a row to references/learned.md.

stop

1. get_running_timer. Nothing running → say so and finish.
2. Show <project> [<code>] · <task> · "<notes>" · <hours>h, running since <timer_started_at as local time>.
3. Ask to confirm. Yes → stop_timer, report the final hours. No → finish.

status

1. get_running_timer and list_time_entries for today.
2. Print the running timer as in stop step 2 (or "no timer running"), then today's entries as a table: project, task, notes, hours, with a total row. Flag any entry whose spent_at is earlier than today but is_running is true.

log

1. Parse the argument: a duration (1.5h, 45m, 1:30) → hours; a clock range (9:00-10:30, 09:00–10:30) → started_time and ended_time. The date is today by default; accept yesterday, a weekday name (the most recent one), or YYYY-MM-DD → spent_at. Anything that parses as neither duration nor range is an error: show the accepted shapes.
2. Resolve the ticket, project and task.
3. list_time_entries for that date. An entry with the same notes and project already exists → show it and ask: add a second entry, or leave it. Leave → finish.
4. Always ask before writing, with the full statement including hours and date. For a weak project include the runners-up and the list as in start.
5. log_time, notes as in start step 4. Report what was written. Learned-row rule as in start step 6.