Spawning Agents

First time spawning an agent? Start with the first agent quickstart — it walks you through one end-to-end. The page below is the reference.

The basic call

fracta spawn <task-name> --runtime claude --contract "Hunt for SSO anomalies in the last 24h."

This creates an agent named <task-name>, picks the claude runtime, hands it the contract as its initial prompt, and supervises the resulting subprocess (or pod, depending on deployment mode) until it exits.

Inputs that shape the agent

Input	What it does
Task name	Identifies the agent in `fracta list`, names its workspace (worktree branch or directory), and is how you address it via `fracta say`, `fracta peek`, `fracta merge`, `fracta kill`.
Runtime	Which AI CLI runs as the agent process — `claude`, `codex`, `opencode`. The runtime adapter handles invocation, session continuation, and output capture.
Contract	The agent’s initial instruction — the what and why of its work. Stored alongside the agent’s state so resumes and `fracta say` follow-ups have the original framing.
Credentials	The control plane materializes a credential profile (LLM keys, MCP backend secrets) into the agent’s environment before launch. See the credential pipeline guide.

What the control plane does on spawn

Admission check. Concurrency limits, queue eligibility. If full, the agent enters the queue.
Workspace creation. Either a git worktree (local-process) or a per-agent directory (Docker Compose / Kubernetes). See Workspaces.
Credential materialization. Profile-driven secrets are written into the agent’s environment.
Process launch. The runtime CLI is started as a subprocess (local-process / Docker Compose) or as a Kubernetes Job (k8s mode).
Wiring. The agent’s MCP client points at the gateway. Its mailbox is initialized. Its intent is set to a default.
State write. The agent appears in fracta list with status running.

Lifecycle states

The orchestrator tracks each agent through a small state machine:

State	Meaning
`queued`	Admission control held it; will start when capacity frees up
`running`	Process is alive and the agent is doing work
`completed`	Process exited cleanly; final output captured
`failed`	Process exited non-zero or crashed
`stopped`	Killed via `fracta kill` (or reaped after timeout)

State transitions are persisted in the state store (SQLite or PostgreSQL). They survive restarts of the control plane.

Talking to an agent after it’s running

Command	What it does
`fracta list`	See every agent — status, intent, last update, unread message count
`fracta peek`	Read an agent’s recent semantic output without disturbing it
`fracta watch`	Stream an agent’s events live over SSE
`fracta say`	Send a follow-up; the agent resumes its session with the new message
`fracta merge`	(Local-process only) Merge the agent’s feature branch into the current branch — agent stays alive
`fracta kill`	Tear it down: workspace removed, branch deleted, state cleaned up

fracta merge is non-destructive — the agent keeps running and can iterate further. fracta kill is the terminal operation.

Spawning many at once

The swarm pattern is many agents in parallel. fracta spawn is happy to be invoked repeatedly:

fracta spawn refactor-auth     --runtime claude --contract "Refactor src/auth.go ..."
fracta spawn refactor-tokens   --runtime claude --contract "Refactor src/tokens.go ..."
fracta spawn upgrade-deps      --runtime codex  --contract "Bump deps in go.mod ..."

Each gets its own workspace; admission control enforces the configured concurrency limit. Use fracta list to watch all of them at once.

Source

Spawn flow: internal/orchestrator/spawn.go
Lifecycle writer: internal/agentlifecycle/
Admission and reaping: internal/admission/

Introduction

Getting Started

Swarm

Strategies

Patterns

Guides

Reference

Operations

Development

Contributing

Spawning Agents

The basic call

Inputs that shape the agent

What the control plane does on spawn

Lifecycle states

Talking to an agent after it’s running

Spawning many at once

Source

​The basic call

​Inputs that shape the agent

​What the control plane does on spawn

​Lifecycle states

​Talking to an agent after it’s running

​Spawning many at once

​Source

The basic call

Inputs that shape the agent

What the control plane does on spawn

Lifecycle states

Talking to an agent after it’s running

Spawning many at once

Source