Self-improving AI Employees for everyone
Claude Code Agent (claude_code_agent)
| Field | Value |
|---|---|
| Category | specialized_agents |
| Plugin | server/nodes/agent/claude_code_agent/__init__.py::ClaudeCodeAgentNode.execute_op (dispatch via BaseNode.execute()) |
| Backend service | server/services/cli_agent/service.py::AICliService.run_batch (provider "claude"); pool _pool.py, argv _provider.py, skill materialiser _skills.py |
| Connection collection | server/services/plugin/edge_walker.py::collect_agent_connections |
| Tests | server/tests/nodes/test_specialized_agents.py::TestClaudeCodeAgent |
Purpose
Runs N parallel Claude Code CLI sessions over a list of ClaudeTaskSpec
tasks via AICliService.run_batch("claude", ...). The pool spawns claude
as a plain subprocess driven over the VSCode-extension stream-json protocol
(--output-format stream-json --input-format stream-json --verbose --ide) —
NOT the old headless claude -p. The common case is a single visible
prompt that synthesises a one-task batch. Memory continuity is handled by
claude's own on-disk session JSONL via a host-minted --session-id on the
first run and --resume <last_session_id> afterwards (never --continue,
which the CLI resolves only against interactive sessions) over a stable
cwd, not by re-injecting markdown. This is the only
specialized-agent node that shells out; the others stay in-process.
Temporal Stop/Resume boundary
Claude Code is excluded from AGENT_WORKFLOW_TYPES; its subprocess, CLI
session, and MCP tool calls execute within a whole node Activity. New controlled
generations (execution_control_version=1) close admission before the next
Activity. An already-admitted Claude Code Activity continues through its
internal tools until it settles under its scheduled timeout/retry policy, then
normal result bookkeeping finishes and the graph/parent agent waits.
Generation Resume releases that existing continuation. It does not launch a
replacement CLI task or repeat a recorded completed Activity. CLI
--resume <session_id> is the plugin's own conversation mechanism and is
distinct from generation Resume. No generic heartbeat cursor serializes a CLI
session or subprocess; ambiguous effects before recorded completion remain
subject to the plugin/tool retry and idempotency contract. Legacy generations
keep their previous control path. See
Temporal workflow control and
Temporal architecture.
Inputs (handles)
Standard std_agent_handles() topology (same as the generic agents).
| Handle | Purpose |
|---|---|
input-main |
Auto-prompt fallback (reads source.message / text / content / str) |
input-skill |
Connected skill names collected; SKILL.md trees materialised under <workspace>/.claude/skills/ and exposed to the CLI (not injected into a system prompt) |
input-context |
Context-node opt-in (ui_hints.requiresContext = True via STD_AGENT_HINTS): a connected context node persists the conversation through SpecializedAgentContextBridge; is_context() tells the descriptor apart from a legacy memory payload (see Decision Logic) |
input-tools |
Connected tool nodes exposed to the CLI as mcp__opencompany__<type> MCP tools |
input-task |
Collected by the edge-walker; task_data is unpacked but the 5th element is ignored (_) here |
Parameters
ClaudeCodeAgentParams — only prompt is visible; every other field carries
json_schema_extra.hidden=True and feeds defaults into the per-task
ClaudeTaskSpec.
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
prompt |
string | "" |
no | - | The prompt sent to Claude Code (only visible field, 4 rows) |
tasks |
ClaudeTaskSpec[] |
[] |
no | hidden | Advanced multi-task batch (max 5 concurrent); null coerced to [] |
model |
enum (ClaudeCodeModel) |
claude-sonnet-4-6 |
no | hidden | --model; aliases sonnet/opus/haiku or pinned IDs; unknown values coerced to default |
system_prompt |
string|null | None |
no | hidden | System prompt (3 rows) |
working_directory |
string|null | None |
no | hidden | Git repo root; defaults to workflow workspace dir |
max_parallel |
int | 5 |
no | hidden | 1-20 concurrency cap |
allowed_credentials |
string[] | [] |
no | hidden | Credential names the CLI may fetch via MCP; null coerced to [] |
effort |
enum|null (ClaudeCodeEffort) |
None |
no | hidden | low/medium/high/xhigh/max via --effort (thinking models) |
fallback_model |
enum|null | None |
no | hidden | --fallback-model; unknown values coerced to None |
Outputs (handles)
Output = ClaudeCodeAgentOutput (extra="forbid") — aggregated batch shape:
| Handle | Shape | Description |
|---|---|---|
output-main / output-top |
object | Batch result (see payload below) |
Output payload
{
success: boolean; // result.n_failed == 0
n_tasks: number;
n_succeeded: number;
n_failed: number;
total_cost_usd: number | null;
wall_clock_ms: number;
tasks: SessionResultModel[]; // per-task result models
provider: "claude";
timestamp: string;
// Legacy single-task convenience (populated when len(tasks) == 1):
response: string | null;
session_id: string | null;
cost_usd: number | null;
}
node_output_schemas.py registers claude_code_agent as AIAgentOutput
(response/thinking/model/provider/finish_reason/timestamp) for the
frontend Input Data panel — a separate, looser schema from the plugin's strict
ClaudeCodeAgentOutput.
Logic Flow
flowchart TD
A[ClaudeCodeAgentNode.execute_op] --> B[broadcast executing]
B --> C[collect_agent_connections<br/>context/skill/tool/input]
C --> D{context_data is a legacy<br/>memory payload, not is_context?}
D -- yes --> D1[resume_session_id =<br/>memory_data.last_session_id]
D -- no --> E{params.tasks empty?}
D1 --> E
E -- yes --> F[Resolve prompt:<br/>params.prompt else input_data<br/>message/text/content/str]
F --> G{prompt empty?}
G -- yes --> H[raise NodeUserError<br/>no prompt]
G -- no --> I[Build single ClaudeTaskSpec]
E -- no --> J[Apply node defaults to each task<br/>model/system_prompt/effort/fallback/continue]
I --> K{memory + len tasks > 1?}
J --> K
K -- yes --> L[raise NodeUserError<br/>memory batch must be serial]
K -- no --> M[Resolve workspace_dir + repo_root]
M --> N[AICliService.run_batch claude]
N --> O[Aggregate result -> dict payload]
O --> P[broadcast success/warning]
Decision Logic
- Prompt resolution: explicit
promptparam wins; otherwise scansinput_dataand readsmessage / text / content / str(same chain as_inline.py). Empty ->NodeUserError. - Single-task synthesis: when
params.tasksis empty, oneClaudeTaskSpecis built fromprompt+model+system_prompt+effort+fallback_model+continue_session. - Batch defaulting: when
params.tasksis non-empty, node-levelmodel/system_prompt/effort/fallback_modelfill any task that didn't override;resume_session_idis auto-set from the memory node'slast_session_idonly when memory is wired AND the task didn't explicitly opt in/out or pick its own UUID. - Context vs legacy memory:
collect_agent_connectionsreturns onecontext_dataslot;is_context()marks a Context-node descriptor (handled bySpecializedAgentContextBridge), anything else is treated as a legacy memory payload (memory_data). - Memory bridge (legacy payload only):
resume_session_id = memory_data["last_session_id"]— the pool reads the persistedlast_session_idand the argv builder emits--resume <UUID>(first run has none, so the pool mints--session-idand_persist_memorystores it for next time; a stale UUID is cleared when claude reports it not found). Never--continue, which skips non-interactive sessions. NO markdown re-injection. - Serial-memory guard: memory wired AND
len(tasks) > 1->NodeUserError(parallel--resumeagainst one JSONL would corrupt it). - Workspace:
ctx.raw["workspace_dir"](injected by workflow.py) orworking_directory; falls back to{workspace_base_resolved}/{workflow_id|default}.
Side Effects
- Subprocess spawn:
AICliService.run_batch->ClaudeSessionPoolspawnsclaudeas a plain-pipe subprocess (no PTY) with--output-format stream-json --input-format stream-json --verbose --ide --permission-mode dontAsk+--allowedTools <mcp tools + conditional Skill + 5 infra tools>+--mcp-config <bearer>+--add-dir <workspace>. Warm subprocesses are reused across turns/batches; crash recovery via--resume <UUID>. - Broadcasts:
StatusBroadcaster.update_node_status-- executing ("Starting Claude Code batch..."), thensuccess/warningon completion (n_succeeded/n_tasks). The pool emits 4 typed CloudEvents (claude.session.{spawned,cleared,terminated,usage}); memory turns emitnode_parameters_updatedso the simpleMemory panel refreshes live. - File I/O: materialises connected SKILL.md trees under
<workspace>/.claude/skills/<name>/(diff-based on warm reuse). Claude keeps its own session JSONL under<CLAUDE_CONFIG_DIR>/projects/<cwd-key>/. - External API: indirect -- the CLI calls Anthropic internally.
External Dependencies
- Binaries:
@anthropic-ai/claude-code, OpenCompany-managed — auto-installed on first use into the shared packages tree at<DATA_DIR>/packages/withbun add --trustviacore.js_runtime.add_package(bin shim at<DATA_DIR>/packages/node_modules/.bin/claude[.exe], executed on the bun runtime); requires bun (OPENCOMPANY_BUN_BINor PATH), never Node or npm. - Python packages: standard library + the
services/cli_agent/framework (FastMCP bridge, session pool). - Credentials: Claude Code handles its own authentication via
CLAUDE_CONFIG_DIR=<DATA_DIR>/claude/(=~/.opencompany/claude/by default; see Claude OAuth); OpenCompany does not inject an API key.
Edge cases & known limits
- No prompt ->
NodeUserError: whentasksis empty AND neitherpromptnor a connectedinput-mainoutput yields text,execute_opraisesNodeUserError(single WARN line, structured envelope). - Memory-bound batches must be serial: memory wired AND
len(tasks) > 1raisesNodeUserError(parallel--resumewould corrupt one JSONL). - Stale-model coercion: legacy saved
model/fallback_modelstrings (dot-spelled, date-suffixed, empty) coerce to the default /Nonevia amode="before"field validator so old workflows still load. - Output is strict (
extra="forbid"): a malformed CLI envelope raises aValidationErrorat the Output boundary instead of emitting an unparseable shape downstream. - Strict tool allowlist:
--permission-mode dontAskenforces--allowedTools(only wiredmcp__opencompany__*tools, conditionalSkill, 5 infra tools); claude's own built-in Read/Edit/Bash/etc. do NOT fire unless wired. - Per-workflow skill isolation: SKILL.md trees materialise under the
workspace's
.claude/skills/, not the repo, so workflow A's skills can't leak into workflow B's subprocess.
Related
- Dedicated-path siblings:
rlmAgent - Generic pattern:
_pattern.md - Architecture: CLI Agent Framework, Claude Code Interactive Mode, Claude Code Agent