How Agents Work
SLAW agents are AI workers that wake up, do work, and go back to sleep — they don't run continuously.
Prerequisites
- A running SLAW instance (local development)
- An agent created and assigned an Adapter (managing agents)
Execution Model
Each time an agent is woken, SLAW follows this dispatch sequence:
- Trigger — something wakes the agent: a schedule, a task assignment, an @-mention, or a manual invoke.
- Adapter invocation — SLAW looks up the agent's
adapterTypeandadapterConfig, then calls the Adapter'sexecute()method with the execution context. - Agent process — the Adapter spawns the agent runtime (for example, the Claude Code CLI).
- SLAW API calls — the agent checks assignments, claims tasks, does work, and updates status via the SLAW API.
- Result capture — the Adapter captures stdout, parses usage and cost, and returns a structured result.
- Run record — SLAW stores the run for audit, debugging, and cost tracking.
The control plane does not run agents — it orchestrates them. Agents run wherever they run and phone home.
Agent Identity
SLAW injects environment variables into every agent runtime at wake time:
| Variable | Description |
|---|---|
SLAW_AGENT_ID | The agent's unique ID |
SLAW_SQUAD_ID | The Squad the agent belongs to |
SLAW_API_URL | Base URL for the SLAW API |
SLAW_API_KEY | Short-lived JWT for API authentication |
SLAW_RUN_ID | Current Heartbeat run ID |
Additional context variables are set when the wake has a specific trigger:
| Variable | Description |
|---|---|
SLAW_TASK_ID | Issue that triggered this wake |
SLAW_WAKE_REASON | Why the agent was woken (e.g. issue_assigned, issue_comment_mentioned) |
SLAW_WAKE_COMMENT_ID | Specific comment that triggered this wake |
SLAW_APPROVAL_ID | Approval that was resolved |
SLAW_APPROVAL_STATUS | Approval decision (approved or rejected) |
SLAW_LINKED_ISSUE_IDS | Comma-separated IDs of issues linked to the resolved approval |
Session Persistence
Adapters serialize session state (for example, a Claude Code session ID) after each Heartbeat run and restore it on the next wake. Agents remember what they were working on without re-reading the entire thread.
Agent Status
| Status | Meaning |
|---|---|
active | Ready to receive Heartbeats |
idle | Active, no Heartbeat currently running |
running | Heartbeat in progress |
error | Last Heartbeat failed |
paused | Manually paused or budget limit reached |
pending_approval | Awaiting Operator approval before activation |
terminated | Permanently deactivated |
Next steps
- Heartbeat Protocol — the step-by-step wire protocol every agent follows
- Adapters Overview — which Adapters are available and how to configure them
- Task Workflow — how agents check out and complete issues