Playbooks — Scape

Playbooks are automation routines — multi-step flows that chain together shell commands, AI prompts, HTTP requests, and Scape tools. Describe what you want in natural language, and Scape generates an executable playbook you can edit, run, and reuse.

Creating a playbook

Open the Creation Picker (Cmd+N) and select Playbook. You can:

Generate from a prompt — describe what the playbook should do and an AI agent builds the flow.
Start from scratch — add cells manually in the canvas editor.

Step types

Each cell in the canvas is one step. Available types:

Step	Purpose	Key outputs
`bash`	Run a shell command	`stdout`, `stderr`, `exitCode`
`claudeSession`	Spawn a Claude session with tools	`text`, `result`
`claudePrompt`	Single LLM prompt (no tools)	`text`
`http`	HTTP request (GET, POST, etc.)	`status`, `body`, `json`, `headers`
`scapeTool`	Call any Scape MCP tool	`text`, `result`
`customTool`	Call a user-defined custom tool	`output`
`subPlaybook`	Invoke another playbook	child outputs
`writeToStore`	Write rows to a data store	`inserted`, `updated`
`readFromStore`	Query a data store	`rows`, `count`
`waitFor`	Poll until a condition is met	`elapsedMs`
`manual`	Pause for human input	`note`

Variables and inputs

Inputs

Declare inputs at the top of a playbook. Reference them in any step with double-brace syntax:

echo "Deploying to {{environment}}"

Step references

Reference output from a previous step using {{steps.<stepId>.<field>}}:

# Use the HTTP response body from a previous step
echo "Got status: {{steps.step_1.status}}"
echo "Body: {{steps.step_1.body}}"

Secrets

Store sensitive values (API keys, tokens) in macOS Keychain via the playbook editor's inputs panel. Reference them with:

curl -H "Authorization: Bearer {{secret:API_KEY}}" https://api.example.com/data

Secrets are resolved at runtime and never persisted to playbook output.

Running playbooks

Manual: Click the Run button in the canvas editor.
MCP tools: Use run_playbook from any agent session.
Sub-playbook: One playbook can call another as a step (max depth 10).

Flow control

Steps execute top-to-bottom by default. For conditional branching, add explicit edges with when expressions. Failed steps can retry via configurable retry.maxAttempts.

Use fanOutOnMatch to fire multiple branches concurrently — they must reconverge at a settlement cell.

Distillation

After a successful run, Distill rewrites exploratory claudeSession cells into deterministic typed cells (bash, HTTP, scapeTool) based on the actual execution trace. This reduces LLM usage on re-runs and makes the playbook faster and cheaper.