Claude Local

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 when permissions allow)
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 (default: true); required for headless runs where interactive approval is impossible

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 compaction (rotation)

Although Claude Code manages its own in-conversation context, a resumed session's cached context still grows without bound across heartbeats — a long-lived thread can re-send millions of cached tokens on every wake even when nothing new happens. Vagaris therefore applies threshold-based session compaction to claude_local (unlike other confirmed-native adapters, which stay unbounded):

Ceiling	Default	Meaning
maxSessionRuns	40	Rotate after this many heartbeats on one session.
maxSessionAgeHours	48	Rotate after the session is this old.
maxCachedInputTokens	2,000,000	Rotate when the latest run's cached (context) input tokens reach this. This is the metric that actually grows on a resumed session; maxRawInputTokens reads the tiny fresh per-call input count and is left at 0.

When any ceiling is crossed, the current session is rotated: a fresh session starts and a handoff summary (previous session id, issue, rotation reason, last-run summary, and issue continuation summary) is injected so the new session continues without re-deriving the whole thread. Override any ceiling per-agent via runtimeConfig.heartbeat.sessionCompaction (maxSessionRuns / maxSessionAgeHours / maxCachedInputTokens / maxRawInputTokens); set a ceiling to 0 to disable it.

The ceilings are intentionally conservative (rotation stays rare-but-real) so that no-op heartbeats on already-terminal issues are also short-circuited before the model is invoked — see the semantic-churn analysis for the cost rationale.

Skills Injection

The adapter creates a temporary directory with symlinks to Vagaris skills and passes it via claude --add-dir. This makes skills discoverable without polluting the agent's working directory.

For manual local CLI usage outside heartbeat runs (for example running as claudecoder directly), use:

vagaris agent local-cli claudecoder --company-id <company-id>

This installs Vagaris skills in ~/.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 (auto-created if missing and permitted)
• API key/auth mode hints (ANTHROPIC_API_KEY vs subscription login)
• A live hello probe (claude --print - --output-format stream-json --verbose with prompt Respond with hello.) to verify CLI readiness