Agents and subagents

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

Role	Responsibility	Tools
general	General implementation tasks	All tools
explore	Read-only repository exploration	read_file, find_files, search_files, list_directory
review	Correctness and regression review	Read-only tools and command execution
planner	Investigation and implementation planning	Read-only tools and command execution

Subagents return results to the main agent rather than talking directly to the user. Roles with command execution can perform writes, subject to tool permissions.

​

The subagent tool

​

single, parallel, and chain

Mode	Behavior
single	One role handles one task
parallel	Multiple tasks run concurrently
chain	Tasks run sequentially; {previous} references the prior result

Authorize delegation in natural language:

Delegate two read-only tasks in parallel: one checks API error handling, the other checks test coverage. Return evidence and suggestions separately, then summarize them in the main agent. Do not modify files.

​

Background tasks

The subagent tool accepts run_in_background. A background task returns a channel ID immediately and posts a notification with a summary, usage, and the sub-session path when it finishes. The Step Code process must remain running while tasks are active.

agent_send operates on background tasks by channel ID:

Action	Effect
reply	Send a follow-up instruction to a background task; single-mode tasks only. Start a new subagent call for other modes
stop	Stop a task
status	Check task state; omit the channel ID to list every background task in the session

Background tasks are limited to 8 concurrent channels and stop automatically after 10 minutes idle. Only the 16 most recent finished tasks are kept; the sub-session paths of older tasks are in their completion notifications.

To run every subagent task in the foreground, set [subagent] background = false in config.toml; see Configuration files.

​

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.

ultraloop Audit test coverage by module. Each subagent checks only its assigned directory and reports missing scenarios. The main agent deduplicates findings and proposes a testing plan.

Multi-agent calls require explicit authorization. This requirement is enforced through instructions; unauthorized calls are logged but not blocked at the execution layer. 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.

STEP_DISABLE_WORKFLOW=1 disables registration.

See Common use cases for examples of multi-agent tasks.

/ultracode [on|off|status|help] manages multi-agent collaboration, with /ultraloop as an alias; /workflows shows workflows and run records. The switch persists per session: restoring the same session restores its state, and a new session without saved state defaults to off.

​

Custom agents

Use Markdown frontmatter for metadata and the body for system instructions:

---
name: db-migrator
description: Design reversible database migrations and review migration scripts
tools: read_file, run_command, edit_file
---

Inspect existing migration conventions before planning. Every migration must include rollback steps.
Do not connect to production databases or run production migrations without explicit authorization.

Item	Description
User directory	~/.stepcode/agent/agents/*.md
Project directory	.stepcode/agents/
Required fields	name, description
Optional fields	tools, model
Same-name precedence	Project overrides user; user overrides built-in

tools accepts an array or comma-separated list. Include project roles explicitly with agentScope: "both" when calling the tool, and confirm when prompted.

See Agent Skills for defining specialized workflows.

See Plugins and packages for distributing agents through plugins.

​

Context isolation and safety

The sandbox VM restricts only the workflow orchestration script. Subtask processes remain subject to OS permissions.

• Subagents have independent context and token usage; the main agent primarily receives summaries.
• Subagents may share the main agent’s working directory, so file changes affect the same working tree.
• 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. See Permissions and safety for shared approval and access rules.