What It Does — Parallel AI Agent Orchestration
Shard is an open-source orchestrator that solves the biggest bottleneck in AI-assisted coding: the idle wait time. Instead of watching a single Claude Code agent work serially on a complex task for 30-60 minutes, Shard automatically decomposes your prompt into a Directed Acyclic Graph (DAG) of parallel sub-tasks. Each sub-task gets exclusive file ownership, eliminating merge conflicts by design. It then dispatches multiple agents across isolated git worktrees simultaneously, merges results in topological order, and self-heals test failures.
Why Claude Code Users Need This
If you've ever given Claude Code a substantial refactoring task or feature implementation and found yourself waiting—unable to intervene or work productively—Shard changes that workflow completely. A 45-minute serial task becomes 4 agents running for approximately 12 minutes. This isn't just faster execution; it's fundamentally different economics for your development time.
Shard is agent-agnostic but specifically supports Claude Code as its recommended backend. It uses your existing Claude Code installation, meaning you don't need to switch tools or learn new prompting patterns.
Setup & Configuration
Install Shard via pip:
pip install shard-code
Ensure you have Claude Code installed globally:
npm install -g @anthropic-ai/claude-code
Create a shard.toml configuration file in your repository root:
[agent]
backend = "claude-code"
max_concurrent = 4
[planner]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
[timeouts]
per_task_s = 600
global_s = 3600
[cost]
max_usd = 5.00
[test]
runner = "pytest"
args = ["-xvs"]
Set your Anthropic API key:
export ANTHROPIC_API_KEY=sk-ant-...
How To Use It
Run a full pipeline with a natural language prompt:
shard run -p "Add user authentication with JWT tokens and refresh token support"
Preview the execution plan without running:
shard plan -p "Refactor the database layer to use async operations"
Customize your run with flags:
shard run -p "Your prompt" \
--agents 4 \
--backend claude-code \
--timeout 3600 \
--max-cost 10.0
Monitor and manage runs:
# Check status
shard status
# Resume interrupted run
shard resume <run-id>
# View task logs
shard logs <task-id>
When It Shines
Shard excels at tasks that naturally decompose into independent components:
- Multi-file refactoring: Changing naming conventions across an entire codebase
- Feature implementation with clear boundaries: Adding authentication, payment processing, or API endpoints
- Test suite generation: Creating comprehensive tests for different modules
- Documentation updates: Updating docs across multiple files or sections
Tasks that are highly sequential or require deep understanding of a single complex algorithm may benefit less from parallelization, but Shard's planner will detect this and create an appropriate DAG.
The Technical Magic: Git Worktrees
Shard's conflict-free parallel execution relies on git worktrees. Each agent gets its own isolated worktree with exclusive ownership of specific files. The planner ensures no two tasks touch the same files. After all agents complete, Shard merges branches in topological order, resolving only structural conflicts (like two agents adding imports to the same file) automatically.
Cost Considerations
The max_usd configuration lets you set hard spending limits. Since Shard runs multiple agents simultaneously, your per-minute cost may be higher, but your total time cost drops dramatically. For a $5 budget with 4 agents running 12 minutes vs 1 agent running 45 minutes, you're trading higher parallel cost for significantly reduced developer wait time—often the more expensive resource.
Self-Healing Test Suite
After merging all changes, Shard runs your test suite (configurable via [test] section). If tests fail, it automatically triggers repair agents to fix the issues, creating a feedback loop that ensures the final merged code actually works.
