Usage Guide
April 27, 2026 · View on GitHub
Hands-on walkthroughs for sage's core workflows. For command-by-command reference see COMMANDS.md; for moat-demonstration stories see use-case-kill-switch.md and use-case-bench.md.
Table of contents
- Parallel multi-runtime security audit
- Headless CI mode
- 8 runtimes, one interface
- MCP + skills ecosystem
- Agent guardrails
- Task templates
- Plan orchestrator
- Live monitoring
- Task tracking
- Tracing
Parallel multi-runtime security audit
Run different AI agents on the same code simultaneously, each in an isolated git branch:
sage create reviewer --worktree review-branch --runtime claude-code
sage create auditor --worktree audit-branch --runtime kiro
sage send --headless --json reviewer "Review cmd_send() for bugs" &
sage send --headless --json auditor "Security audit cmd_send()" &
wait
# reviewer (Claude Code, 12s): 3 bugs — unsafe ls parsing, missing error handling
# auditor (Kiro, 41s): 6 issues — path traversal, command injection, unsafe glob
# Wall time: 41s (parallel), not 53s (sequential)
Headless CI mode
No tmux, no terminal, structured JSON out:
sage send --headless --json reviewer "Is this safe? eval(\$user_input)"
{
"status": "done",
"task_id": "headless-1775793946",
"exit_code": 0,
"elapsed": 34,
"output": "UNSAFE. eval \"$user_input\" is a critical command injection vulnerability..."
}
GitHub Action:
- uses: youwangd/SageCLI@main
with:
runtime: claude-code
task: "Review this PR for security issues"
8 runtimes, one interface
sage create a1 --runtime claude-code # Anthropic Claude (Bedrock)
sage create a2 --runtime gemini-cli # Google Gemini
sage create a3 --runtime codex # OpenAI Codex
sage create a4 --runtime cline # Cline
sage create a5 --runtime kiro # Kiro (Bedrock)
sage create a6 --runtime ollama --model llama3.2:3b # local
sage create a7 --runtime llama-cpp # local GGUF
sage create a8 --runtime bash # custom shell handler
# Identical JSON output regardless of runtime:
sage send --headless --json a1 "Review this code"
sage send --headless --json a6 "Review this code"
MCP + skills ecosystem
sage mcp add github --command "npx" --args "@modelcontextprotocol/server-github"
sage create dev --runtime claude-code --mcp github
sage skill install https://github.com/user/code-review-skill
sage create reviewer --runtime claude-code --skill code-review-pro
sage send reviewer "Review PR #42"
Agent guardrails
sage create worker --runtime claude-code --timeout 30m # auto-kill after 30m
sage create worker --runtime claude-code --max-turns 50 # stop after 50 tasks
sage env set worker API_KEY=sk-xxx
sage env set worker DATABASE_URL=postgres://...
Task templates
Predefined templates with checklists and structured output:
sage task --list
# review (auto) Code review with prioritized findings
# test (auto) Generate comprehensive test suite
# spec (auto) Write technical specification
# implement (auto) Implement a feature from spec
# refactor (auto) Refactor code while preserving behavior
# document (auto) Generate documentation
# debug (auto) Debug and fix a reported issue
sage task review src/auth.py src/middleware.py
sage task test src/api/ --message "Focus on edge cases"
sage task refactor src/legacy.py --timeout 180
sage task debug --message "Users report 500 on /login after upgrade"
Templates live in ~/.sage/tasks/ as markdown files with YAML frontmatter (runtime preference, input type, checklist).
Background mode:
sage task implement --message "Add JWT refresh tokens" --background
# ✓ task t-123 → sage-task-implement-... (background)
Plan orchestrator
Decompose complex goals into dependency-aware task waves with automatic parallel execution:
sage plan "Build a Python REST API with auth, CRUD endpoints, tests, and docs"
# 📋 Plan: Build a Python REST API...
#
# #1 [spec] Define API schema and auth strategy
# #2 [implement] Build auth module (depends: #1)
# #3 [implement] Build CRUD endpoints (depends: #1)
# #4 [test] Write test suite (depends: #2, #3)
# #5 [document] Generate API docs (depends: #2, #3)
#
# Waves:
# Wave 1: #1
# Wave 2: #2, #3 (parallel)
# Wave 3: #4, #5 (parallel)
#
# [a]pprove [e]dit [r]eject
How it works:
- Planning agent decomposes the goal
- Output normalized across LLM JSON formats
- Dependency waves computed with cycle detection
- Each wave executes in parallel
- Results from completed tasks flow as context to downstream
sage plan "Refactor auth to OAuth2" --yes # skip interactive prompt
sage plan "Migrate database" --save migration.json # save for later
sage plan --run migration.json # run a saved plan
sage plan --resume ~/.sage/plans/plan-1710347041.json # skip completed
sage plan --list # saved plans
sage plan --pattern fan-out "Audit repo" # swarm pattern
Live monitoring
sage peek master --lines 20
⚡ peek: master
Live output:
I'll create a professional restaurant template with modern design...
Runner log:
[22:15:28] master: invoking claude-code...
→ ToolSearch
→ TodoWrite
→ Write
Workspace: 4 file(s)
22:17 19889 styles.css
22:16 23212 index.html
sage attach drops you into the tmux session directly. sage dashboard gives a live TUI across all agents.
Task tracking
Every task has a trackable ID. State transitions are mechanical, not LLM-driven:
queued → running → done
sage send worker "Build the entire app"
# ✓ task t-1710347041 → worker
sage tasks worker
# TASK AGENT STATUS ELAPSED FROM
# t-1710347041 worker running 45s cli
sage result t-1710347041
sage wait worker
Tracing
# Timeline
sage trace
# 17:00:40 send cli → orch "Build the app..."
# 17:01:02 send orch → sub1 "Write fibonacci..."
# 17:01:20 done sub1 ✓ 18s
# 17:02:08 done orch ✓ 88s
# Call hierarchy
sage trace --tree
# t-123 cli → orch "Build the app" (88s) ✓
# ├─ t-456 orch → sub1 "Write fibonacci..." (18s) ✓
# └─ t-789 orch → sub2 "Write factorial..." (16s) ✓
sage trace orch # filter to one agent
sage trace --tree -n 50 # last 50 events as tree