Skip to main content
Step Code delegates tasks to four built-in roles, supports custom agents defined in Markdown, and uses workflow to coordinate agents in parallel.

​
Built-in agents

Subagents return results to the main agent rather than talking directly to the user. A role with command execution is not read-only at the OS level; behavior still depends on tool permissions.

​
Custom agents

Use Markdown frontmatter for metadata and the body for system instructions:
tools accepts an array or comma-separated list. Include project roles explicitly with agentScope: "both" when calling the tool, and confirm when prompted.

​
The subagent tool

​
single, parallel, and chain

The task batch limit is 8, with execution concurrency of 4 by default. Dispatch follows the current approval policy. Subagents cannot recursively create subagents. Authorize delegation in natural language:

​
Background lanes

run_in_background: true creates a background lane and immediately returns its ID / alias. Completion arrives as a notification. agent_send supports reply (queued or inserted immediately) and stop, addressed by agent_id, alias, group, or all. Background tasks still depend on the Step Code process; they are not independent system daemons.

​
Workflow and ultraloop

Workflow executes JavaScript orchestration in a sandbox VM without network or filesystem access. Primitives include phase(), parallel(), pipeline(), agent(), and iterate(). Run records are stored in .stepcode/workflows/runs/ and support resuming. Use /workflows to inspect saved workflows and recent runs.
Multiple agents require explicit authorization: include ultraloop or ultracode, or enable session-level authorization with /ultraloop on and disable it with /ultraloop off. Single-message authorization does not carry forward and is not inferred from task size. Unauthorized calls are logged, not blocked at the execution layer; the constraint is enforced through instructions. STEP_DISABLE_WORKFLOW=1 disables registration. The orchestration script’s restricted VM does not mean subtask processes are OS-isolated. Authorization conventions do not replace OS permissions.

​
Context isolation and safety

  • Subagents have independent context and token usage; the main agent primarily receives summaries.
  • The default working directory may be shared with the main agent. Separate context does not isolate file changes.
  • Assign disjoint files for parallel writes, or explicitly arrange separate Git worktrees.
  • Worktrees isolate working trees, not access to other directories, networks, or credentials.
  • Review diffs and tests before integrating results. Do not clean up unmerged work blindly.
The default scale is medium, approximately up to 15 agents, unless explicitly expanded. Each subagent consumes tokens independently; the main context receives conclusions.

​
Next steps