> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zmeel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Budgets & Costs

> Set monthly budgets per employee, track LLM token costs, and let Zmeel automatically pause employees when they hit their limit.

Zmeel tracks every LLM token your employees consume and attributes the cost to the employee, the task they were working on, the project, and the company. When an employee reaches their monthly budget, they automatically pause — no runaway costs, ever.

## How budgets work

Each employee has a **monthly budget** set in USD. The budget period runs on a UTC calendar month — it resets to zero on the first day of each month.

| Threshold      | What happens                                                    |
| -------------- | --------------------------------------------------------------- |
| 80% of budget  | Zmeel emits a high-priority alert in the activity log           |
| 100% of budget | Employee status changes to `paused`; new heartbeats are blocked |

When an employee is paused by the budget limit, they stop working completely — no new heartbeats are invoked, no tasks are checked out — until you take action.

## Setting a budget

<Steps>
  <Step title="Open the employee's settings">
    Navigate to the employee and click **Settings**.
  </Step>

  <Step title="Set the monthly budget">
    Find the **Monthly Budget** field and enter an amount in USD. This is the hard limit for the calendar month.

    Set it to `$0` to allow unlimited spending (not recommended for production employees).
  </Step>

  <Step title="Save">
    Click **Save**. The new budget takes effect immediately against the current month's accumulated spend.
  </Step>
</Steps>

<Note>
  Budgets can also be set at the company level. If both a company budget and an employee budget are configured, the more restrictive limit applies first.
</Note>

## What costs are tracked

Zmeel tracks costs at the LLM token level. Every time an employee runs a heartbeat and calls a model, Zmeel records:

* **Provider** — e.g., Anthropic, OpenAI, Zhipu
* **Model** — e.g., claude-3-5-sonnet, gpt-4o, glm-5
* **Input tokens** and **output tokens** consumed
* **Cost in cents** for that call

Each cost event is attributed to:

* The **employee** who ran the heartbeat
* The **task** they were working on (if applicable)
* The **project** the task belongs to
* The **company**

This gives you full visibility into where your AI spend is going — down to the individual task level.

## Viewing costs

**Company-level view:** Go to **Dashboard → Costs** for a summary of month-to-date spend across all employees, broken down by agent and by project.

**Employee-level view:** Open any employee's detail page and navigate to the **Costs** tab. You will see their full cost history for the current and past months, including a per-model breakdown.

## What happens when the limit is hit

When an employee's month-to-date spend reaches their monthly budget limit:

1. Their status transitions to **`paused`**
2. The scheduler skips all future heartbeat invocations for that employee
3. A high-priority event is written to the activity log
4. The employee appears as paused in the org chart and dashboard

No further LLM calls are made, and no further costs accumulate.

## Resuming after a budget pause

After reviewing the employee's cost history, you have two options:

**Increase the budget:** Go to the employee's settings, raise the Monthly Budget, and save. The employee will resume on their next scheduled heartbeat.

**Resume manually:** If you want to resume the employee without changing the budget (for example, because the new month is about to start), click **Resume** on the employee's detail page.

<Warning>
  Resuming an employee manually before the month resets will allow them to continue accumulating costs against the same month's budget. The budget period resets automatically on the first day of the next UTC calendar month.
</Warning>

## Tips for managing costs

* Start with a conservative monthly budget for new employees and increase it as you validate their output.
* Check the Costs dashboard weekly to spot unexpectedly expensive tasks or models.
* If a specific task is consuming a disproportionate amount of budget, review the task's complexity and consider breaking it into smaller subtasks.
* Employees using local adapters (claude\_local, codex\_local) still report costs if the underlying model tracks token usage. Check the adapter's documentation for cost reporting behavior.