Claude Code (claude-code)

Category: agents | Form: | Symbol: Cc

Anthropic Claude Code agent — real CLI terminal in a sandboxed VM

Runs Anthropic’s Claude Code CLI as an interactive terminal session. Requires CODER_WORKER_URL (isolation executor) to be set — without it, start_session fails. Use start_session to create a PTY session (default 120x40), returns ws_path for WebSocket terminal I/O. Use generate/invoke for headless single-prompt execution with NDJSON streaming. Set spec.model (default: claude-sonnet-4-6), spec.max_turns (default: 30), spec.permission_mode (default: bypassPermissions). Set spec.system_prompt for custom instructions. Set spec.allowed_tools/spec.disallowed_tools to control tool access. Supports snapshot/restore — stopped sessions can be resumed (~22ms restore). Timeout defaults to 5 minutes (spec.timeout_ms). For the composable agent with tool modifiers, use agent instead. For multi-provider CLI agents, use open-code.

Guide

Anthropic Claude Code agent — real CLI terminal in a sandboxed VM

What It Does

Claude Code runs Anthropic’s Claude Code CLI as an interactive terminal session inside a Firecracker VM. The user interacts through a PTY-over-WebSocket bridge in the portal. Sessions can be snapshotted when idle and restored on next interaction (~22ms restore time). For headless execution, use the generate/invoke operations which spawn the CLI as a subprocess with NDJSON streaming.

Element Definition

Property	Value
Type	claude-code
Category	agents
Form	atom
Symbol	terminal / #D97706

Properties

Field	Type	Default	Description
model	string	claude-sonnet-4-6	Claude model to use
max_turns	integer	30	Maximum LLM turns per session
system_prompt	string	—	Custom system prompt for the CLI
permission_mode	string	bypassPermissions	Permission mode for the CLI
output_format	string	stream-json	Output format for headless mode
timeout_ms	integer	300000	Maximum execution time (5 minutes default)
allowed_tools	array	—	Whitelist of CLI tools to allow
disallowed_tools	array	—	Blacklist of CLI tools to block

Topology

• Lives in: agents/claude-code/ repository
• Referenced by: projects
• Accepts modifiers: rate-limit, auth-policy, protection

Quick Start

Creating via API

POST /api/{circle}/{project}/
Content-Type: application/json

{
  "element_type": "claude-code",
  "slug": "my-claude",
  "name": "My Claude Code",
  "spec": {
    "model": "claude-sonnet-4-6",
    "system_prompt": "You are a Rust developer working on a web service."
  }
}

Interactive Session

Start a terminal session (requires isolation executor):

POST /api/{circle}/{project}/my-claude/ops/start_session

{
  "cols": 120,
  "rows": 40
}

Response includes ws_path for WebSocket terminal I/O.

Headless Execution

POST /api/{circle}/{project}/my-claude/ops/invoke

{
  "prompt": "Add error handling to the parse_config function"
}

Operations

Operation	Method	Description
start_session	POST	Start interactive terminal session
stop_session	POST	Stop/suspend a session
resize_terminal	POST	Resize terminal dimensions
sessions	GET	List all sessions
session_get	GET	Get session details
discard_session	POST	Permanently delete session
generate/invoke	POST	Headless single-prompt execution
generations	GET	List generation history
generation_get	GET	Get generation details

Common Mistakes

No isolation executor configured. Interactive sessions require CODER_WORKER_URL to be set. Without it, start_session returns an error. Headless mode (generate/invoke) works without the executor.

Using claude-code when you need composable tools. Claude Code uses the real CLI with its own built-in tools. For composable tool control (attach/detach specific capabilities), use the triformer element instead.

Session not persisted after force terminate. Setting force_terminate: true on stop_session kills the process immediately without creating a snapshot. The session cannot be restored afterward.

State Guidance

State	Guidance	Next actions
draft	Configure model and permissions, then transition to ready.
error	Session encountered an error. Reset and start a new session.	Reset to ready: triform_ops(action: "call", slug: "{slug}", operation: "lifecycle", input: { target_state: "ready" })
ready	Ready to start a session.	Start a session: triform_ops(action: "call", slug: "{slug}", operation: "start_session")
running	Terminal session is active. Interact via WebSocket or send headless prompts.
suspended	Session is suspended (VM snapshot saved). Resume to continue where you left off (~22ms restore).	Resume session: triform_ops(action: "call", slug: "{slug}", operation: "start_session")

Authoring Hints

Field	Help	Example
allowed_tools	Allowed tools. Whitelist of tool names the agent can use. Empty = all tools allowed.	``
disallowed_tools	Disallowed tools. Blacklist of tool names the agent cannot use.	``
max_turns	Max turns. Maximum tool-use turns per prompt. Default 30.	``
model	Claude model. Which Claude model to use. Default: claude-sonnet-4-6.	claude-sonnet-4-6
permission_mode	Permission mode. Tool permission policy: bypassPermissions (default, auto-approve all), default (ask user), or strict.	``
system_prompt	System prompt. Custom instructions prepended to every prompt.	``
timeout_ms	Timeout (ms). Max session duration in ms. Default 300000 (5 minutes).	``

Error Recovery

Error	Recovery guidance	Next actions
auth	Claude API authentication failed. Check that the platform has valid Anthropic credentials.
executor_unavailable	Isolation executor not reachable. Ensure CODER_WORKER_URL is set and the executor service is running.
session_timeout	Session timed out. Increase spec.timeout_ms or break the task into smaller prompts.	Increase timeout: triform_ops(action: "call", slug: "{slug}", operation: "update", input: { spec: { timeout_ms: 600000 } })

Relationships

• Attaches to: rate-limit, auth-policy, api-token, filter-words, evaluator, prompt, variable
• Uses: sql, document, vector, graph, timeseries

Capabilities

• companion: Can serve as an interactive companion in the workspace
• interactive-terminal: Real PTY terminal with bidirectional I/O over WebSocket
• snapshot-restore: VM snapshotted on idle, restored in ~22ms on interaction
• coding: Full coding capabilities via Claude Code’s built-in tools
• self-authenticating: User authenticates via /login in the terminal — no credential storage
• persistence: Session state persists across snapshots via VM memory + disk
• workspace-access: Circle workspace mounted into VM filesystem

Properties

Property	Type	Default	Description
idle_timeout_seconds	integer	30	Seconds of inactivity before the VM is snapshotted. Lower = faster resource reclaim, higher = less snapshot/restore churn.
session_ttl_hours	integer	24	Maximum session lifetime in hours. After this, the snapshot is discarded and a new session must be started.
auto_resume	boolean	true	Automatically restore the last session when reopening the terminal. If false, starts a fresh session.
memory_mb	integer	1024	VM memory in MB. Claude Code itself needs ~256MB, rest is for tool execution.
vcpus	integer	2	Virtual CPUs for the VM
disk_gb	integer	10	Workspace disk size in GB
network_access	boolean	true	Allow outbound network access from the VM (needed for /login OAuth and package installs)
terminal_cols	integer	120	Initial terminal width in columns
terminal_rows	integer	40	Initial terminal height in rows
shell	string	"/bin/bash"	Login shell before claude CLI is started
allowed_tools	array	[]	Whitelist of tool names the agent can use (maps to –allowedTools). Empty = all tools allowed.
disallowed_tools	array	[]	Blacklist of tool names the agent cannot use (maps to –disallowedTools). Applied to both the interactive terminal and headless runs.
permission_mode	string	"bypassPermissions"	Tool permission policy. bypassPermissions auto-approves all tool use (passes –dangerously-skip-permissions); default and strict make the CLI prompt (no skip flag is passed).
claude_config	object	—	Optional Claude Code settings written to ~/.claude/settings.json in the VM
workspace_source	string	"circle"	What to mount as /workspace. ‘circle’ = full circle repo, ‘empty’ = blank workspace.
mount_readonly_paths	array	[]	Additional paths mounted read-only into the VM (e.g., shared libraries)

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attach

Post /ops/attach | Auth: Read

Attach this actor to a target element

Call this ON the modifier/resource element, passing target_id of the actor. The target’s contract.yaml must declare the modifier kind in attaches: or uses:. Priority controls evaluation order for modifiers (lower = first).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

detach

Post /ops/detach | Auth: Read

Detach this actor from a target element

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

discard_session

Post /ops/session/discard | Auth: Execute

Permanently delete a suspended session’s snapshot

Permanently delete a session and its snapshot. Cannot be undone.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

get_attached_modifiers

Get /ops/attached | Auth: Read

Get elements that are attached to this actor

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

invoke

Post /ops/invoke | Auth: Execute

Invoke the actor with input

Always include data:{} even for no-input actors. Use ?stream=true for streaming output (agents support this). Use ?async=true to get a run_id immediately and poll via run_get. Input must match the actor’s port schema (check via schema operation). Creates a run record in execution history.

list_attachments

Get /ops/targets | Auth: Read

List all elements this agent is attached to

Returns all target elements where this agent is currently attached. Shows target_id, target_type, priority, and cascade_policy.

logs

Get /ops/logs | Auth: Read

Get execution logs

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

resize_terminal

Post /ops/session/resize | Auth: Execute

Resize the terminal (sent when the portal window changes size)

Resize an active terminal session. Pass terminal_id, cols, rows.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

run_cancel

Post /ops/runs/{run_id}/cancel | Auth: Execute

Cancel a running execution

Only works on runs with status pending or running. Already-completed or failed runs cannot be cancelled. The run transitions to cancelled state and triggers run.cancelled event.

run_get

Get /ops/runs/{run_id} | Auth: Read

Get details of a specific run

runs

Get /ops/runs | Auth: Read

List execution runs

Filter with ?status=completed|failed|running, paginate with ?limit=N&offset=N. Default limit is 50. Returns total count for pagination.

schema

Get /ops/schema | Auth: Read

Get input/output port schemas (MCP tools/list compatible)

Call this before invoking an actor to discover its expected input/output format. Returns MCP-compatible tool definitions — useful for building dynamic tool UIs or A2A integration.

session_get

Get /ops/sessions/{session_id} | Auth: Read

Get details of a specific session

Get details of a specific terminal session. Pass session_id.

sessions

Get /ops/sessions | Auth: Read

List all sessions for this element (active, suspended, terminated)

List all terminal sessions for this element including status and creation timestamps.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

start_session

Post /ops/session/start | Auth: Execute

Start or resume an interactive Claude Code terminal session

Start an interactive Claude Code terminal session on the isolation executor. Set cols/rows for terminal size (defaults: 120x40). Returns ws_path for WebSocket connection and terminal_id. Requires CODER_WORKER_URL to be configured. Resource env vars from attached elements are injected.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

stop_session

Post /ops/session/stop | Auth: Execute

Stop an active session. Snapshots automatically unless force_terminate=true.

Stop a running terminal session. Pass terminal_id. Set force_terminate: true to kill immediately (no snapshot), otherwise session is suspended and can be restored.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

write_stdin

Post /ops/session/stdin | Auth: Execute

Write a line of text to a running terminal session’s stdin PTY.

Sends text + newline to the PTY of a running session. Does not await output — use ws-terminal WebSocket for streaming output. Requires a running session_id. Returns {written: true} on success.

ws-terminal

Get /ops/ws/terminal | Auth: Write

Interactive PTY terminal over WebSocket. Binary frames carry raw PTY I/O; text frames carry JSON control messages (resize, lifecycle, ping).

Error Codes

Code	Class	Retryable	Description
CLAUDE_CODE_VM_FAILED	internal	yes	Firecracker VM failed to start or crashed
CLAUDE_CODE_SNAPSHOT_FAILED	internal	yes	VM snapshot failed — session continues but won’t survive disconnect
CLAUDE_CODE_RESTORE_FAILED	internal	yes	Failed to restore from snapshot — falls back to new session
CLAUDE_CODE_SESSION_EXPIRED	timeout	no	Session TTL exceeded — snapshot discarded
CLAUDE_CODE_RESOURCE_LIMIT	limit	no	VM resource limits exceeded (memory, disk, CPU)