https://github.com/ek33450505/cast-parallel
CAST parallel execution — managed-agent dispatch and fan-out coordination
https://github.com/ek33450505/cast-parallel
agents ai-agents anthropic cast claude-code cli developer-tools open-source parallel shell worktree worktrees
Last synced: 13 days ago
JSON representation
CAST parallel execution — managed-agent dispatch and fan-out coordination
- Host: GitHub
- URL: https://github.com/ek33450505/cast-parallel
- Owner: ek33450505
- License: mit
- Created: 2026-04-06T18:32:58.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-04T02:47:30.000Z (20 days ago)
- Last Synced: 2026-06-04T04:22:41.119Z (20 days ago)
- Topics: agents, ai-agents, anthropic, cast, claude-code, cli, developer-tools, open-source, parallel, shell, worktree, worktrees
- Language: Shell
- Size: 22.5 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# cast-parallel
[](https://github.com/ek33450505/cast-parallel/actions/workflows/ci.yml)
Split CAST plan execution across parallel worktree sessions — two Claude Code agents working side-by-side on the same repo, each in its own isolated git worktree, results merged automatically when both finish.
## Install
```bash
brew tap ek33450505/cast-parallel
brew install cast-parallel
```
Or manually:
```bash
curl -fsSL https://raw.githubusercontent.com/ek33450505/cast-parallel/main/install.sh | bash
```
## Usage
```bash
cast-parallel [--dry-run] [--split N]
```
### Flags
| Flag | Description |
|------|-------------|
| `--dry-run` | Show how batches would be split without executing anything |
| `--split N` | Split after batch N (default: auto-midpoint) |
| `--help`, `-h` | Show usage |
### Examples
```bash
# Preview the split without running anything
cast-parallel --dry-run ~/.claude/plans/my-feature.md
# Execute with auto-midpoint split
cast-parallel ~/.claude/plans/my-feature.md
# Force split after batch 2 (batches 1-2 in Stream A, rest in Stream B)
cast-parallel --split 2 ~/.claude/plans/my-feature.md
```
### Exit Codes
| Code | Meaning |
|------|---------|
| `0` | Both sessions completed and merged successfully |
| `1` | Runtime error, session failure, or merge conflict |
| `2` | Usage or argument error (missing plan file, invalid flags) |
## How It Works
cast-parallel reads an **Agent Dispatch Manifest** (ADM) — a JSON block embedded in a CAST plan file — and splits its batches across two concurrent Claude Code sessions.
### When to use cast-parallel
For most parallel agent work, **prefer `cast-managed-agent.sh --fork`** from the [CAST framework](https://github.com/ek33450505/claude-agent-team) — it runs agents on Anthropic infrastructure with no local filesystem contention, no worktree cleanup, and no merge step.
cast-parallel is purpose-built for one specific case the managed approach doesn't cover: **local, plan-file-driven 2-stream worktree splits with automatic merge**. If you have an Agent Dispatch Manifest plan and want to bisect its batches across two local Claude Code sessions with deterministic worktree handoff and merge, this is the right tool. Otherwise, reach for `--fork`.
### Execution Flow
```
Plan File (.md)
│
├── Parse ────── Extract `json dispatch` block, count batches
│
├── Split ────── Divide batches at midpoint (or --split N)
│ Stream A: batches 1..N
│ Stream B: batches N+1..total
│
├── Worktrees ── Create two git worktrees at ~/.claude/worktrees/
│ parallel-a (branch: cast-parallel-a-)
│ parallel-b (branch: cast-parallel-b-)
│
├── Launch ───── Start two `claude --headless` background processes
│ Each gets its own worktree, its own batch list
│ No terminal windows — runs silently in background
│
├── Wait ─────── Monitor both PIDs, capture exit codes
│ If either fails: print log tails, exit 1
│
├── Merge ────── git merge Stream B into Stream A
│ git merge Stream A into your original branch
│ Conflicts = exit 1, worktrees preserved for manual fix
│
└── Cleanup ──── Remove worktrees, prune stale refs, delete temp branches
```
### Plan File Format
cast-parallel expects a markdown file containing a fenced code block tagged `json dispatch`:
````markdown
```json dispatch
{
"plan_id": "my-feature",
"batches": [
{
"id": 1,
"description": "Build the thing",
"parallel": true,
"agents": [
{ "subagent_type": "code-writer", "prompt": "..." },
{ "subagent_type": "test-writer", "prompt": "..." }
]
},
{
"id": 2,
"description": "Review and commit",
"parallel": false,
"agents": [
{ "subagent_type": "commit", "prompt": "..." }
]
}
]
}
```
````
This is the standard [CAST Agent Dispatch Manifest](https://github.com/ek33450505/claude-agent-team) format.
### Safety
- **Subprocess guard** — if `CAST_SUBPROCESS=1` is set, the script exits immediately to prevent recursive execution inside agent chains
- **Trap handler** — `INT`/`TERM` signals kill both background sessions and clean up worktrees
- **No auto-resolve** — merge conflicts are never auto-resolved; worktrees are preserved so you can inspect and fix manually
- **Branch isolation** — each stream works on a unique branch (`cast-parallel-a-`) that is deleted after merge
### Logging
When a CAST database logger (`cast-db-log.py`) is available, events are logged to `cast.db` at each stage: `parallel_start`, `parallel_streams_done`, `parallel_complete`, `parallel_fail`, and `parallel_merge_conflict`.
## Requirements
- **Claude Code CLI** (`claude`) — the headless sessions use `claude --headless --dangerously-skip-permissions`
- **git** — worktree support (git 2.5+)
- **python3** — JSON parsing for the ADM block
- **CAST framework** (recommended) — provides the plan format and database logging
## CAST Ecosystem
> Auto-synced from [claude-agent-team/docs/ecosystem.md](https://github.com/ek33450505/claude-agent-team/blob/main/docs/ecosystem.md). Run `~/Projects/personal/claude-agent-team/scripts/sync-ecosystem-readme.sh` to refresh.
| Repo | Description | Latest | Install |
|---|---|---|---|
| [cast-hooks](https://github.com/ek33450505/cast-hooks) | 13 auditable hook scripts — observability, safety guards, quality gates. SessionStart, PreToolUse, PostToolUse, PostCompact. |  | `brew tap ek33450505/cast-hooks && brew install cast-hooks` |
| [cast-agents](https://github.com/ek33450505/cast-agents) | 23 specialist agents — commit, debug, review, plan, test, research, and more. Agent definitions with YAML frontmatter. v7-synced. |  | `brew tap ek33450505/cast-agents && brew install cast-agents` |
| [cast-memory](https://github.com/ek33450505/cast-memory) | Persistent agent memory with FTS5 search, relevance scoring, shared pool, semantic embeddings. Per-agent knowledge accumulation. |  | `brew tap ek33450505/cast-memory && brew install cast-memory` |
| [cast-routines](https://github.com/ek33450505/cast-routines) | Scheduled autonomous Claude Code routines via YAML + cron. Daily briefings, inbox triage, release celebration, weekly cost reports. |  | `brew tap ek33450505/cast-routines && brew install cast-routines` |
| [cast-parallel](https://github.com/ek33450505/cast-parallel) | Parallel agent execution across worktree sessions. Agent Dispatch Manifest (ADM) support. |  | `brew tap ek33450505/cast-parallel && brew install cast-parallel` |
| [cast-observe](https://github.com/ek33450505/cast-observe) | Session-level observability — cost tracking, agent run history, token spend, event sourcing. Feeds cast.db. |  | `brew tap ek33450505/cast-observe && brew install cast-observe` |
| [cast-security](https://github.com/ek33450505/cast-security) | Security hooks and audit trails. PII redaction, parry-guard integration, compliance logging. |  | `brew tap ek33450505/cast-security && brew install cast-security` |
| [cast-doctor](https://github.com/ek33450505/cast-doctor) | Read-only health check for any Claude Code install. Validates hooks, MCP servers, agent frontmatter, cast.db schema, stale memories. |  | `brew tap ek33450505/cast-doctor && brew install cast-doctor` |
| [cast-time](https://github.com/ek33450505/cast-time) | Gives Claude Code a clock — injects local time, timezone, and a semantic time-of-day bucket at every SessionStart. |  | `brew tap ek33450505/cast-time && brew install cast-time` |
| [cast-dash](https://github.com/ek33450505/cast-dash) | Terminal UI dashboard for live swarm monitoring. 4-panel real-time display (Textual framework). |  | `brew tap ek33450505/cast-dash && brew install cast-dash` |
| [cast-claudes_journal](https://github.com/ek33450505/cast-claudes_journal) | Session continuity — Claude's Journal auto-injects prior-day context via SessionStart hook. Obsidian vault sync. |  | `brew tap ek33450505/homebrew-claudes-journal && brew install claudes-journal` |
| [cast-website](https://github.com/ek33450505/cast-website) | castframework.dev — marketing site and docs portal for the CAST ecosystem. |  | — |
| [cast-desktop](https://github.com/ek33450505/cast-desktop) | Tauri 2 native app — embedded PTY terminal, command palette, 11 dashboard views. |  | `brew tap ek33450505/homebrew-cast-desktop && brew install cast-desktop` |
## License
MIT
---
Part of the [CAST ecosystem](https://github.com/ek33450505/claude-agent-team).