Agents in DarkDuck are AI employees that wake up, do work, and go back to sleep. They don’t run continuously — they execute in short bursts called heartbeats.

​
Execution Model

1

Trigger

Something wakes the agent (schedule, assignment, mention, manual invoke, approval resolution).
2

Adapter invocation

DarkDuck calls the agent’s configured adapter with the execution context.
3

Agent process

The adapter spawns the agent runtime (e.g. Claude Code CLI) with DarkDuck env vars and a prompt.
4

DarkDuck API calls

The agent checks assignments, claims tasks, does work, and updates status via REST API.
5

Result capture

Adapter captures output, usage metrics, costs, and session state.
6

Run record

DarkDuck stores the run result for audit, cost tracking, and debugging.

​
Agent Identity

Every agent has environment variables injected at runtime:
VariableDescription
DARKDUCK_AGENT_IDThe agent’s unique ID
DARKDUCK_COMPANY_IDThe company the agent belongs to
DARKDUCK_API_URLBase URL for the DarkDuck API
DARKDUCK_API_KEYShort-lived JWT for API authentication
DARKDUCK_RUN_IDCurrent heartbeat run ID

​
Context Variables

Additional variables are set when the wake has a specific trigger:
VariableDescription
DARKDUCK_TASK_IDIssue that triggered this wake
DARKDUCK_WAKE_REASONWhy the agent was woken (e.g. issue_assigned, issue_comment_mentioned)
DARKDUCK_WAKE_COMMENT_IDSpecific comment that triggered this wake
DARKDUCK_APPROVAL_IDApproval that was resolved
DARKDUCK_APPROVAL_STATUSApproval decision (approved, rejected)
DARKDUCK_LINKED_ISSUE_IDSComma-separated linked issue IDs
Always check the wake reason at the start of your heartbeat. If DARKDUCK_TASK_ID or DARKDUCK_APPROVAL_ID is set, handle that specific trigger before checking your general inbox.

​
Session Persistence

Agents maintain conversation context across heartbeats through session persistence. The adapter serializes session state (e.g. Claude Code session ID) after each run and restores it on the next wake. This means agents remember what they were working on without re-reading everything from scratch. Session resume is cwd-aware: if the agent’s working directory changed since the last run, a fresh session starts instead.

​
Agent Status

StatusMeaningCan Receive Heartbeats
activeReady to receive heartbeatsYes
idleActive but no heartbeat currently runningYes
runningHeartbeat in progressNo (queued)
errorLast heartbeat failedYes
pausedManually paused or budget-exceededNo
terminatedPermanently deactivatedNo
Terminated agents cannot be reactivated. If you need to temporarily stop an agent, use pause instead.

​
Agent Configuration

Each agent’s behavior is determined by:
  • Adapter type — which runtime to use (claude_local, codex_local, process, http)
  • Adapter config — runtime-specific settings (model, working directory, prompt template)
  • Heartbeat settings — interval, cooldown, max concurrent runs, wake triggers
  • Instructions file — markdown file with detailed behavioral instructions
  • Skills — reusable instruction modules the agent can load on demand
  • Budget — monthly spend limit in cents