Parallel autopilot with file ownership partitioning
Parallel autopilot that spawns multiple workers with file ownership partitioning for maximum speed.
Ultrapilot is the parallel evolution of autopilot. It decomposes your task into independent parallelizable subtasks, assigns non-overlapping file sets to each worker, and runs them simultaneously.
Key Capabilities:
Speed Multiplier: Up to 5x faster than sequential autopilot for suitable tasks.
/oh-my-claudecode:ultrapilot <your task>
/oh-my-claudecode:up "Build a full-stack todo app"
/oh-my-claudecode:ultrapilot Refactor the entire backend
These phrases auto-activate ultrapilot:
Ultrapilot Excels At:
Autopilot Better For:
User Input: "Build a full-stack todo app"
|
v
[ULTRAPILOT COORDINATOR]
|
Decomposition + File Partitioning
|
+-------+-------+-------+-------+
| | | | |
v v v v v
[W-1] [W-2] [W-3] [W-4] [W-5]
backend frontend database api-docs tests
(src/ (src/ (src/ (docs/) (tests/)
api/) ui/) db/)
| | | | |
+---+---+---+---+---+---+---+---+
|
v
[INTEGRATION PHASE]
(shared files: package.json, tsconfig.json, etc.)
|
v
[VALIDATION PHASE]
(full system test)
Goal: Determine if task is parallelizable
Checks:
Output: Go/No-Go decision (falls back to autopilot if unsuitable)
Goal: Break task into parallel-safe subtasks
Agent: Architect (Opus)
Method: AI-Powered Task Decomposition
Ultrapilot uses the decomposer module to generate intelligent task breakdowns:
import {
generateDecompositionPrompt,
parseDecompositionResult,
validateFileOwnership,
extractSharedFiles
} from 'src/hooks/ultrapilot/decomposer';
// 1. Generate prompt for Architect
const prompt = generateDecompositionPrompt(task, codebaseContext, {
maxSubtasks: 5,
preferredModel: 'sonnet'
});
// 2. Call Architect agent
const response = await Task({
subagent_type: 'oh-my-claudecode:architect',
model: 'opus',
prompt
});
// 3. Parse structured result
const result = parseDecompositionResult(response);
// 4. Validate no file conflicts
const { isValid, conflicts } = validateFileOwnership(result.subtasks);
// 5. Extract shared files from subtasks
const finalResult = extractSharedFiles(result);
Process:
Output: Structured DecompositionResult:
{
"subtasks": [
{
"id": "1",
"description": "Backend API routes",
"files": ["src/api/routes.ts", "src/api/handlers.ts"],
"blockedBy": [],
"agentType": "executor",
"model": "sonnet"
},
{
"id": "2",
"description": "Frontend components",
"files": ["src/ui/App.tsx", "src/ui/TodoList.tsx"],
"blockedBy": [],
"agentType": "executor",
"model": "sonnet"
},
{
"id": "3",
"description": "Wire frontend to backend",
"files": ["src/client/api.ts"],
"blockedBy": ["1", "2"],
"agentType": "executor-low",
"model": "haiku"
}
],
"sharedFiles": [
"package.json",
"tsconfig.json",
"README.md"
],
"parallelGroups": [["1", "2"], ["3"]]
}
Decomposition Types:
| Type | Description | Use Case |
|---|---|---|
DecomposedTask | Full task with id, files, blockedBy, agentType, model | Intelligent worker spawning |
DecompositionResult | Complete result with subtasks, sharedFiles, parallelGroups | Full decomposition output |
toSimpleSubtasks() | Convert to string[] for legacy compatibility | Simple task lists |
Goal: Assign exclusive file sets to workers
Rules:
Data Structure: .omc/state/ultrapilot-ownership.json
{
"sessionId": "ultrapilot-20260123-1234",
"workers": {
"worker-1": {
"ownedFiles": ["src/api/routes.ts", "src/api/handlers.ts"],
"ownedGlobs": ["src/api/**"],
"boundaryImports": ["src/types.ts"]
},
"worker-2": {
"ownedFiles": ["src/ui/App.tsx", "src/ui/TodoList.tsx"],
"ownedGlobs": ["src/ui/**"],
"boundaryImports": ["src/types.ts"]
}
},
"sharedFiles": ["package.json", "tsconfig.json", "src/types.ts"],
"conflictPolicy": "coordinator-handles"
}
Goal: Run all workers simultaneously
Spawn Workers:
// Pseudocode
workers = [];
for (subtask in decomposition.subtasks) {
workers.push(
Task(
subagent_type: "oh-my-claudecode:executor",
model: "sonnet",
prompt: `ULTRAPILOT WORKER ${subtask.id}
Your exclusive file ownership: ${subtask.files}
Task: ${subtask.description}
CRITICAL RULES:
1. ONLY modify files in your ownership set
2. If you need to modify a shared file, document the change in your output
3. Do NOT create new files outside your ownership
4. Track all imports from boundary files
Deliver: Code changes + list of boundary dependencies`,
run_in_background: true
)
);
}
Monitoring:
Max Workers: 5 (Claude Code limit)
Goal: Merge all worker changes and handle shared files
Process:
Agent: Executor (Sonnet) - sequential processing
Conflict Resolution:
Goal: Verify integrated system works
Checks (parallel):
Agents (parallel):
Retry Policy: Up to 3 validation rounds. If failures persist, detailed error report to user.
Location: .omc/ultrapilot-state.json
{
"sessionId": "ultrapilot-20260123-1234",
"taskDescription": "Build a full-stack todo app",
"phase": "execution",
"startTime": "2026-01-23T10:30:00Z",
"decomposition": { /* from Phase 1 */ },
"workers": {
"worker-1": {
"status": "running",
"taskId": "task-abc123",
"startTime": "2026-01-23T10:31:00Z",
"estimatedDuration": "5m"
}
},
"conflicts": [],
"validationAttempts": 0
}
Location: .omc/state/ultrapilot-ownership.json
Tracks which worker owns which files (see Phase 2 example above).
Location: .omc/ultrapilot/progress.json
{
"totalWorkers": 5,
"completedWorkers": 3,
"activeWorkers": 2,
"failedWorkers": 0,
"estimatedTimeRemaining": "2m30s"
}
Optional settings in .claude/settings.json:
{
"omc": {
"ultrapilot": {
"maxWorkers": 5,
"maxValidationRounds": 3,
"conflictPolicy": "coordinator-handles",
"fallbackToAutopilot": true,
"parallelThreshold": 2,
"pauseAfterDecomposition": false,
"verboseProgress": true
}
}
}
Settings Explained:
maxWorkers - Max parallel workers (5 is Claude Code limit)maxValidationRounds - Validation retry attemptsconflictPolicy - "coordinator-handles" or "abort-on-conflict"fallbackToAutopilot - Auto-switch if task not parallelizableparallelThreshold - Min subtasks to use ultrapilot (else fallback)pauseAfterDecomposition - Confirm with user before executionverboseProgress - Show detailed worker progress/oh-my-claudecode:cancel
Or say: "stop", "cancel ultrapilot", "abort"
Behavior:
If ultrapilot was cancelled or a worker failed:
/oh-my-claudecode:ultrapilot resume
Resume Logic:
/oh-my-claudecode:ultrapilot Build a todo app with React frontend, Express backend, and PostgreSQL database
Workers:
Shared Files: package.json, docker-compose.yml, README.md
Duration: ~15 minutes (vs ~75 minutes sequential)
/oh-my-claudecode:up Refactor all services to use dependency injection
Workers:
Shared Files: src/types/services.ts, tsconfig.json
Duration: ~8 minutes (vs ~32 minutes sequential)
/oh-my-claudecode:ultrapilot Generate tests for all untested modules
Workers:
Shared Files: jest.config.js, test-utils.ts
Duration: ~10 minutes (vs ~50 minutes sequential)
.omc/ultrapilot/progress.jsonExclusive Ownership:
Shared Files:
Boundary Files:
For each file in codebase:
If file in shared_patterns (package.json, *.config.js):
→ sharedFiles
Else if file imported by 2+ subtask modules:
→ boundaryFiles
→ Assign to most relevant worker OR defer to shared
Else if file in subtask directory:
→ Assign to subtask worker
Else:
→ sharedFiles (safe default)
Automatically classified as shared:
package.json, package-lock.jsontsconfig.json, *.config.js, *.config.ts.eslintrc.*, .prettierrc.*README.md, CONTRIBUTING.md, LICENSEDockerfile, docker-compose.yml.github/**, .gitlab-ci.ymlUnexpected Overlap:
Shared File Contention:
Boundary File Conflict:
coordinator-handles (default):
abort-on-conflict:
Decomposition fails?
.omc/ultrapilot/decomposition.json for detailsWorker hangs?
.omc/logs/ultrapilot-worker-N.logIntegration conflicts?
.omc/ultrapilot-state.json conflicts arrayValidation loops?
Too slow?
| Feature | Autopilot | Ultrapilot |
|---|---|---|
| Execution | Sequential | Parallel (up to 5x) |
| Best For | Single-threaded tasks | Multi-component systems |
| Complexity | Lower | Higher |
| Speed | Standard | 3-5x faster (suitable tasks) |
| File Conflicts | N/A | Ownership partitioning |
| Fallback | N/A | Can fallback to autopilot |
| Setup | Instant | Decomposition phase (~1-2 min) |
Rule of Thumb: If task has 3+ independent components, use ultrapilot. Otherwise, use autopilot.
You can provide a custom decomposition file to skip Phase 1:
Location: .omc/ultrapilot/custom-decomposition.json
{
"subtasks": [
{
"id": "worker-auth",
"description": "Add OAuth2 authentication",
"files": ["src/auth/**", "src/middleware/auth.ts"],
"dependencies": ["src/types/user.ts"]
},
{
"id": "worker-db",
"description": "Add user table and migrations",
"files": ["src/db/migrations/**", "src/db/models/user.ts"],
"dependencies": []
}
],
"sharedFiles": ["package.json", "src/types/user.ts"]
}
Then run:
/oh-my-claudecode:ultrapilot --custom-decomposition
IMPORTANT: Delete state files on completion - do NOT just set active: false
When all workers complete successfully:
# Delete ultrapilot state files
rm -f .omc/state/ultrapilot-state.json
rm -f .omc/state/ultrapilot-ownership.json
Planned for v4.1:
Planned for v4.2: