Project budgets

Project budgets live on the project detail page. Use them when a project has a fixed cap, a monthly retainer, or an internal target you want Hourdini to watch while you keep tracking normally.

Add a budget

Open the project detail page and use the Budget section. A budget needs:

• Period. Lifetime, monthly, quarterly, or yearly. Monthly, quarterly, and yearly budgets use UTC calendar windows. Lifetime budgets count all completed entries on the project.
• Basis. Billable only, or all tracked time.
• Cap. Set an hours cap, an amount cap, or both. Amount caps use the project currency.
• Thresholds. Warn and critical percentages. Defaults are 75% and 100%.

If both hours and amount caps are set, Hourdini uses whichever usage percentage is higher for threshold checks.

What counts toward usage

Budget usage is based on completed time entries. Running timers do not count until they are stopped.

For billable only budgets, non-billable entries are ignored. For all time budgets, every completed entry counts toward hours. Amount usage still only accrues from billable entries, because non-billable time has no billable amount.

Notifications

When a project crosses its warn or critical threshold, Hourdini can send a Project budget threshold notification. Configure delivery under Settings -> Notifications.

Agent-connected workflows can also read these notifications through the MCP notification resource.

CLI and API

The same budget can be managed from the CLI:

hourdini budget set "acme dashboard" --period monthly --hours 40 --warn 75 --critical 100
hourdini budget show "acme dashboard"
hourdini budget clear "acme dashboard"

The REST API exposes:

• GET /api/v1/projects/{id}/budget
• PUT /api/v1/projects/{id}/budget
• DELETE /api/v1/projects/{id}/budget
• GET /api/v1/projects/{id}/budget/usage

See the API reference for request and response shapes.

Next