The claude_local adapter runs Anthropic’s Claude Code CLI locally. It supports session persistence, skills injection, and structured output parsing.
Prerequisites
- Claude Code CLI installed (
claude command available)
ANTHROPIC_API_KEY set in the environment or agent config
Configuration Fields
| Field | Type | Required | Description |
|---|
cwd | string | Yes | Working directory for the agent process (absolute path; created automatically if missing) |
model | string | No | Claude model to use (e.g. claude-opus-4-6) |
promptTemplate | string | No | Prompt used for all runs |
env | object | No | Environment variables (supports secret refs) |
timeoutSec | number | No | Process timeout (0 = no timeout) |
graceSec | number | No | Grace period before force-kill |
maxTurnsPerRun | number | No | Max agentic turns per heartbeat (defaults to 300) |
dangerouslySkipPermissions | boolean | No | Skip permission prompts (dev only) |
Prompt Templates
Templates support {{variable}} substitution:
| Variable | Value |
|---|
{{agentId}} | Agent’s ID |
{{companyId}} | Company ID |
{{runId}} | Current run ID |
{{agent.name}} | Agent’s name |
{{company.name}} | Company name |
Session Persistence
The adapter persists Claude Code session IDs between heartbeats. On the next wake, it resumes the existing conversation so the agent retains full context.
Session resume is cwd-aware: if the agent’s working directory changed since the last run, a fresh session starts instead. If resume fails with an unknown session error, the adapter automatically retries with a fresh session.
Session persistence is one of the key advantages of the Claude Local adapter. Agents maintain conversation context across heartbeats without re-reading everything, which saves tokens and improves task continuity.
Skills Injection
The adapter creates a temporary directory with symlinks to DarkDuck skills and passes it via --add-dir. This makes skills discoverable without polluting the agent’s working directory.
For manual local CLI usage outside heartbeat runs:
pnpm darkduck agent local-cli claudecoder --company-id <company-id>
~/.claude/skills, creates an agent API key, and prints shell exports to run as that agent.
Environment Test
Use the “Test Environment” button in the UI to validate the adapter config. It checks:
- Claude CLI is installed and accessible
- Working directory is absolute and available
- API key/auth mode hints (
ANTHROPIC_API_KEY vs subscription login)
- A live hello probe to verify CLI readiness
The environment test runs a lightweight probe that does not consume significant tokens. It verifies that the full execution pipeline works end-to-end.
