A Swift-native runtime for directing agentic ensembles.
Archived January 2026. This is the SDK exactly as it shipped in the Circuit v1 demo — unmodified, with its history intact. It is not maintained.
Circuit v1 references this package locally, at ../cascade-sdk, so the two
repositories must be cloned side by side:
parent/
├── Circuit/
└── cascade-sdk/
Development of the runtime continued inside Circuitv2, which absorbed this package into a monorepo on 2026-01-21 and evolved it there through March 2026. This repository is the last standalone point.
cascade-sdk provides infrastructure for multi-agent coordination where humans stay meaningfully in the loop. Rather than top-down orchestration, cascades flow through agent systems, surfacing decision moments through escalation.
Key concepts:
- Cascade — The process you direct. Work flows through the system, agents execute in parallel, and when the system encounters ambiguity, it escalates to you.
- Orchestrator — The AI actor that operates cascades. It decomposes prompts into work units, delegates to agents, integrates results, and knows when to escalate.
- Director — You. The human who initiates cascades and shapes their trajectory through escalation responses.
This is distinct from cybernetic orchestration (Kubernetes, Airflow). Cascades are humanist—the human isn't a supervisor monitoring dashboards, but a director shaping a live process.
- Pluggable inference providers — Claude, OpenAI-compatible (Groq, Together, Ollama), CoreML, Apple Foundation Models
- Complete tool suite — File operations (read, write, edit, glob, search), schema output
- Parallel delegation — Work units execute concurrently across multiple agents
- Integration with conflict resolution — Merge results, detect conflicts, generate diffs
- Escalation system — Surface ambiguities, open questions, and drift to the director
- Coherence validation — Ensure the assembled whole makes sense
Add to your Package.swift:
dependencies: [
.package(url: "https://github.com/angelsbrood/cascade-sdk", from: "1.0.0")
]Then import:
import CascadeSDKFor simple tasks without orchestration:
let provider = ClaudeProvider(apiKey: "sk-...")
let agent = CircuitAgent(
provider: provider,
projectRoot: projectURL,
configuration: .init(maxIterations: 12)
)
let schema = try await agent.run(prompt: "Analyze this project")For complex tasks with decomposition, parallel execution, and escalation:
// Create orchestration provider (cloud or local)
let orchestrationProvider = CloudOrchestrationAdapter(
provider: ClaudeProvider(apiKey: "sk-...")
)
// Create orchestrator with initial schema
let orchestrator = Orchestrator(
orchestrationProvider: orchestrationProvider,
localProvider: foundationModelsProvider,
cloudProviders: ["claude": claudeProvider],
initialSchema: schema,
projectRoot: projectURL
)
// Set delegates for progress and escalation
await orchestrator.setDelegate(myDelegate)
await orchestrator.setEscalationDelegate(myEscalationDelegate)
// Process — this triggers the cascade
let result = try await orchestrator.process(prompt: "Add user authentication")
// Result contains successful units, failed units, and the updated schemaThe orchestrator surfaces decision moments through the escalation delegate:
class MyEscalationHandler: EscalationDelegate {
func orchestrator(_ orchestrator: Orchestrator, needsAnswers questions: [OpenQuestion]) async {
// Display questions to user, collect answers
for question in questions {
let answer = await presentQuestionToUser(question)
try await orchestrator.answer(question.id, with: answer)
}
}
func orchestrator(_ orchestrator: Orchestrator, needsResolution conflict: IntegrationConflict) async {
// Present conflict, get user decision
let resolution = await presentConflictToUser(conflict)
try await orchestrator.resolveConflict(conflict.id, resolution: resolution)
}
}Director (Human)
│
│ initiates, responds to escalations
▼
Cascade (the process)
│
│ operated by
▼
Orchestrator ─────────────────────────────┐
│ │
│ decomposes, delegates, integrates │ escalates
▼ ▼
┌─────────┬─────────┬─────────┐ ┌─────────────┐
│ Agent A │ Agent B │ Agent C │ │ Director │
│ (Claude)│ (Groq) │ (Local) │ │ (Human) │
└────┬────┴────┬────┴────┬────┘ └─────────────┘
│ │ │
▼ ▼ ▼
Results integrated into schema + codebase
| Provider | Use Case |
|---|---|
ClaudeProvider |
Anthropic Claude API |
OpenAICompatibleProvider |
OpenAI, Groq, Together, Ollama, LM Studio |
CoreMLProvider |
On-device models (Qwen Coder) |
FoundationModelsProvider |
Apple Intelligence (macOS 26+) |
MockProvider |
Unit testing |
RecordingProvider |
Transcript capture |
- Circuit — v1, the LED Grid build demoed January 2026; the app this runtime was built for
- Circuitv2 — the monorepo that absorbed this package and continued its development
- cassiespiral.com/work/circuit
MIT