Docs · Beta

per.hr for Claude Code

The plugin logs your Claude Code sessions in per.hr: your time, agent time, compute and what shipped, on the right client, project and Plan item. Sessions wait in To Review until you confirm them, so nothing reaches an invoice without you.

Getting Started

You need a per.hr account in the beta, Claude Code, and bash, git and curl (on Windows, the Git Bash that Claude Code already uses). Setup takes about five minutes.

Create a key. In per.hr, open Configure → Data → Claude Code and choose Create a Key. Copy it: it's shown once.
Install the plugin in each repo you want recorded. From the repo's folder, outside a Claude session:
```
claude plugin marketplace add per-hr/claude-code-plugin
claude plugin install perhr@perhr --scope project
```
Paste your key when Claude Code asks. The plugin is installed for that project only, so your other repos are never recorded. Its source is public at github.com/per-hr/claude-code-plugin.
Connect the repo to a project. Start Claude Code in the repo once; the repo then appears on the Claude Code card. Choose the project its work belongs to, or Don't Record.
Give your Plan items references. In Work → Plan, give each item a short reference such as PAY-214. You use it to tell the plugin what you're working on.
Optional: record compute. To see cost, tokens and commits, add the settings block from the card to your user settings, ~/.claude/settings.json (on Windows, %USERPROFILE%\.claude\settings.json), then start a new session.

The card checks off each step as per.hr sees it happen.

Commands

Run these inside Claude Code.

/perhr:start PAY-214Work on a Plan item. Run it at the start of a session, or whenever you move to other items.

/perhr:statusYour time, agent time and cost so far, and how much of the item's estimate is used.

/perhr:pauseStop recording for a call, a break or anything you don't bill.

/perhr:resumeStart recording again.

/perhr:doneSend the session to To Review now, with a one-line summary of what shipped.

Switching items. If you run /perhr:start with another reference after you've started working, the work so far goes to To Review on the first item and the rest of the session records on the new one.

Several items at once. When one stretch of work covers several Plan items, give them all to /perhr:start:

A range: /perhr:start PAY-214:PAY-216, or the short form PAY-214:216. Numbers in the range that aren't on the project are left out.
A list: PAY-214+PAY-220, or with spaces or commas between them.
Both: PAY-214:216+PAY-220. Up to 10 items.

Your time splits between the items in proportion to their estimates (an item without one counts as an hour). Change the split in To Review before confirming, and confirming adds one time entry per item.

Branch names. A branch named with the reference, such as feat/pay-214-reset, attaches the session to that item on its own.

How Your Time Is Counted

per.hr records two clocks for each session.

Your time is the span you were attending the session: from your first prompt to the end, including the time you spend reading, testing and thinking between prompts, and the time Claude spends working while you watch.
Agent time is how long Claude worked: each turn, plus each subagent running alongside it.

A few rules keep your time honest:

A gap of more than 15 minutes with Claude idle is a break and isn't counted. The prompt that ends it counts one minute.
The plugin's own commands (/perhr:start, /perhr:done and the rest) aren't counted as prompts, and running one after a session is reviewed doesn't start a new one.
While Claude is working, your time keeps counting. A stretch of more than an hour with no activity at all counts 15 minutes.
/perhr:pause stops the clock until you resume. Closing Claude Code ends it.
A session that crosses midnight shows both dates in To Review, along with the hours of breaks left out.

Your time is what bills on the Your Time basis. Agent time and compute show on the receipt so the client sees the effort behind it.

Reviewing Sessions

Sessions arrive in Work → To Review when you run /perhr:done, close Claude Code, or after 30 quiet minutes. Each card shows the item, both clocks, compute, commits and lines changed, and the summary. Edit the summary, the Plan items or how your time splits between them if needed, then:

Confirm adds a time entry on the item at your rate, or one per item when the session covers several.
Dismiss keeps nothing (a spike, an experiment, personal work).
Undo Confirm, under Recently Confirmed, sends a session back to To Review and removes its time entries, as long as that time isn't billed and its week isn't submitted.

Sessions with no prompts (Claude Code opened and closed) are set aside on their own and never show.

Billing Clients

Choose how each client pays for AI-assisted work on the Clients page (the sparkle button). There are two bases:

Your Time: your hours at your rate, as with any other work.
Delivered Effort: each finished Plan item bills its agreed hours at your rate, however fast the agents made it. Your time on the item is included, not billed again.

You can also show a receipt on invoices (your time, agent time, compute, what shipped) and share a page with the work behind each invoice. If a client doesn't allow AI-assisted work, mark it there: its sessions wait in To Review with a warning and can't be confirmed. Compute is shown and never billed.

What per.hr Receives

Session start and end; prompt, turn and subagent times (never the prompts); the repo's remote, folder name and branch; and, with compute on, the model, tokens, cost and commit and line counts. Summaries are what you write or approve.

Your prompts, code and files stay on your computer. Events from repos you haven't connected are dropped on arrival, and so is compute from sessions the plugin didn't start. Your key is stored as a hash; revoke it on the card and the plugin stops sending at once.

Troubleshooting

Claude Code says the repo isn't connected: Connect it to a project on the Claude Code card, then start a new session.
/perhr:start says there's no Plan item: The reference has to match an item on the repo's project. Check it in Work → Plan, or add the item there.
The plugin step never checks off: Make sure you pasted the key, and that bash, git and curl are available. On Windows, Claude Code needs Git Bash.
Compute shows Not Recorded: The settings block goes in your user settings file, not the repo's, and only new sessions pick it up.
I confirmed the wrong session: Use Undo Confirm under Recently Confirmed in To Review, then fix the item and confirm again.
My time looks low: Breaks over 15 minutes with Claude idle are left out. The card shows how many hours were. Paused time isn't counted either.

Questions or problems? Contact us.