> ## Documentation Index
> Fetch the complete documentation index at: https://ade-ac1c6011-ade-im-seeing-error-messag-eright-58df792e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Workers & Budget
> Hire and manage CTO worker agents, configure token budgets, set up practical workflows like PR review and feature delegation, and troubleshoot common issues.
## Worker Agents (Employees)
Workers are the CTO's execution arms. The CTO plans and delegates; workers implement.
### Worker types
Persistent workers are assigned to a role and can stay available across wakeups. Use them for ongoing responsibilities like "review PRs in this repository" or "monitor the auth module and flag regressions".
A persistent worker has a standing identity, capabilities, runtime settings, and optional heartbeat configuration. It returns to idle when the task is complete.
Ephemeral workers are created for a single task and dissolved when that task is complete. The CTO creates ephemeral workers automatically when it decides a task needs dedicated execution — for example, when it receives a complex request in chat or when a Linear issue comes in that requires implementation.
Ephemeral workers report results back to the CTO before dissolving.
### Hiring a worker manually
You can create a worker from the **Team sub-tab** without going through the CTO chat:
In CTO > Team, click the **Hire Worker** button.
Fill in:
* **Name** — a human-readable identifier (e.g., "test-writer", "pr-reviewer")
* **Role, title, and capabilities** — describe the worker's focus area
* **Linear identity matching** — user IDs, display names, or aliases that map Linear assignments to this worker
* **Adapter and model/process command** — the runtime configuration used for work
* **Budget** — monthly dollar budget tracked for this worker
* **Heartbeat** — optional timer-based wakeups, wake-on-demand, active hours, and max concurrency
Click **Hire**. The worker appears in the Team org chart with `idle` status. The CTO can use it on the next applicable task delegation or worker wakeup.
### Worker activity visibility
Worker activity is visible in two places:
* **CTO > Team** — the org chart shows each worker's current status, assigned task, and budget consumption
* **Lanes tab** — if a worker is active in a lane, that lane shows the "active" indicator with the worker's name as the agent label
***
## Budget Management
Workers have configurable monthly budgets for tracking and routing decisions. Provider/session caps are configured separately under AI provider settings.
### Budget hierarchy
```
AI provider/session caps
└── Worker monthly budgets
├── Worker: auth-specialist
├── Worker: test-writer
└── Ephemeral worker runtime settings
```
### How budget enforcement works
* **Worker budgets**: CTO > Team stores a monthly dollar budget on each worker identity.
* **Provider/session caps**: Settings > AI Providers and chat/session settings control runtime provider budgets and usage display.
### Configuring budgets
Configure worker budgets in **CTO > Team** when hiring or editing a worker. The value is stored on the worker identity; ADE does not parse a project-level `.ade/ade.yaml` `cto.budget` block.
***
## Practical Workflows
### Asking the CTO to review a PR
1. Open **CTO > Chat**.
2. Type: *"Please review PR #142 and give me a summary of the changes, any concerns, and whether it's safe to merge."*
3. The CTO reads the PR diff (via the GitHub integration ADE CLI tool), checks it against current repository context, checks for conflicts with active lanes, and returns a structured review with: summary, concerns, risk level, and a recommendation.
The CTO's review is informed by accumulated project knowledge — it will note if a change contradicts an architectural decision made last month, or if a test is missing for a pattern it has seen cause regressions before.
### Delegating a feature to a worker
1. Open **CTO > Chat**.
2. Describe the feature: *"I need a new endpoint: `POST /api/v2/users/:id/preferences` that saves user preference objects. Follow the existing pattern in the `preferences` module."*
3. The CTO analyzes the request, identifies the relevant context (existing patterns, related files, open issues), creates an ephemeral worker with appropriate specialization, assigns it to a new lane, and generates a Lane Pack with the task intent.
4. The worker's progress is visible in Lanes (the new lane will show `active`) and in CTO > Team.
5. When the worker completes, the CTO reports back in the chat thread with a summary, a link to the new lane, and (if configured) a Linear issue update.
### Getting a daily project summary
You can ask the CTO for a narrative summary of recent activity at any time:
*"Summarize what changed in the project since yesterday morning. What's blocked? What shipped? What's at risk?"*
The CTO draws from available project context, recent lane state, and PR status to produce a structured summary.
### Routing an incoming request via Automations
To have external webhooks or scheduled triggers start work automatically, configure an Automation with real action types such as `agent-session` or `ade-action`:
```yaml theme={null}
# Example: start an agent session for new Linear issues
automations:
- id: "linear-triage"
name: "Linear triage"
trigger:
type: "linear.issue_created"
execution:
kind: "agent-session"
laneMode: "reuse"
executor:
mode: "automation-bot"
prompt: "Triage the new Linear issue and recommend whether to create a lane, assign a worker, or flag it for human review."
```
***
## CTO Worker Configuration Reference
Worker identity and heartbeat settings are managed in **CTO > Team** and stored in ADE's local worker identity state. Project automation rules still live in `.ade/ade.yaml`.
```yaml theme={null}
# Worker runtime state shape, shown for reference only.
runtimeConfig:
heartbeat:
enabled: true
intervalSec: 300
wakeOnDemand: true
activeHours:
start: "09:00"
end: "22:00"
timezone: "local"
maxConcurrentRuns: 1
```
***
## Troubleshooting
The CTO requires at least one AI provider to be configured. Check **Settings > AI Providers** and verify that a provider is active and its credentials are valid. The CTO also needs the ADE RPC socket to be ready — if you see socket or RPC errors in the main process log, restart ADE.
This is usually expected. Timer wakeups can complete with `HEARTBEAT_OK` when no action is required. Check the worker run history or logs for the heartbeat result.
If no heartbeat appears, verify that the worker has **Timer-based heartbeat** enabled, a positive interval in seconds, and active hours that include the current time.
Review the worker's monthly budget in CTO > Team and the active provider/session budget in Settings > AI Providers or the chat/session controls. Increase the relevant cap or route the work to a cheaper model when needed.
Check the **Linear sub-tab** for the sync status indicator. Common causes:
* **Token expired** — re-authenticate via OAuth or update the personal access token
* **Missing permissions** — the Linear token needs `issues:write` scope for outbound sync
* **Project not selected** — confirm the relevant Linear project is selected in CTO > Linear > Projects
* **Rate limited** — Linear has API rate limits; the CTO backs off automatically and retries. The sync status shows the next retry time.
The CTO relies on current repository evidence and configured project context. If the architecture has changed significantly, update the source docs or ask the CTO to re-read the relevant files before delegating.
If a worker has been `active` for an unusually long time without producing checkpoints, it may be stuck in a loop or waiting for a tool response. From **CTO > Team**, select the worker and click **Inspect**. This opens the worker's live terminal output so you can see exactly what it is doing. You can then:
* Click **Interrupt** to send a stop signal and ask the CTO to reassess the task
* Click **Override** to inject a message directly into the worker's context
* Click **Dissolve** to terminate the worker and return the task to the CTO queue