Skip to main content

​
Introduction to Longshot

Longshot is a massively parallel autonomous coding system that takes natural-language build requests and transforms them into working code. It decomposes any project into hundreds of granular tasks and executes them simultaneously in isolated cloud sandboxes.

Architecture

Understand the system components and how they work together

How it works

Learn the execution flow from request to completion

Installation

Get started with Longshot CLI installation

Configuration

Configure LLM endpoints, workers, and sandboxes

​
What makes Longshot different

Longshot is designed for massive parallelism and stateless execution. Unlike traditional coding agents that work sequentially, Longshot:
  • Decomposes intelligently: A root planner breaks requests into granular tasks, with subplanners handling complex scopes recursively (up to 3 levels deep)
  • Executes in parallel: Runs up to 50 workers simultaneously, each in an isolated Modal sandbox with its own repository clone
  • Stays stateless: Workers are ephemeral, state lives only in Git, and the orchestrator runs locally while execution happens in the cloud
  • Self-heals: A reconciler monitors build health and automatically spawns fix tasks when tests break or conflicts arise

​
Core capabilities

​
Parallel task execution

User request → Root Planner (LLM)
    ├── Task 1 → Worker (Modal Sandbox) → Branch 1
    ├── Task 2 → Worker (Modal Sandbox) → Branch 2
    ├── Task 3 → Subplanner → Subtasks 3.1-3.5 (parallel) → Branches
    └── Task N → Worker (Modal Sandbox) → Branch N
           ↓
      Merge Queue (sequential, priority-ordered)
           ↓
      Main Branch (tested, green)
Each worker operates in complete isolation with:
  • Full repository clone
  • Independent file system
  • Dedicated LLM session
  • Automatic branch management

​
Intelligent decomposition

The system uses a three-tier planning hierarchy:
  1. Root Planner: Analyzes the build request and creates high-level tasks based on SPEC.md, FEATURES.json, and current repository state
  2. Subplanners: Decompose tasks with large scopes (4+ files) into smaller subtasks, up to 3 levels deep
  3. Workers: Execute atomic tasks in isolated sandboxes using the Pi coding agent
Scope-based routing: Tasks with fewer than 4 files go directly to workers. Larger tasks are automatically routed through subplanners for decomposition.

​
Self-healing reconciliation

A background reconciler continuously monitors main branch health: 
// Reconciler sweep (every 5 minutes)
if (!buildOk || !testsOk || hasConflictMarkers) {
  // LLM analyzes failures and generates fix tasks
  const fixTasks = await llm.generateFixTasks({
    buildOutput,
    testOutput,
    conflictFiles
  });
  
  // Inject high-priority fix tasks into the queue
  for (const task of fixTasks) {
    planner.injectTask({ ...task, priority: 1 });
  }
}

​
Merge queue with conflict handling

Branches flow through a serial merge queue with:
  • Priority ordering: Fix tasks (priority 1) merge before feature tasks (priority 5)
  • Automatic rebasing: Failed merges trigger automatic rebase + retry (up to 2 attempts)
  • Conflict resolution: After retries exhausted, creates a conflict-fix task with detailed instructions

​
Example workflow

Here’s how Longshot handles a typical build request:
1

User submits request

longshot "Build a REST API with user authentication and todo CRUD"
2

Root planner analyzes

Reads SPEC.md, examines repository structure, and creates initial tasks:
  • task-001: Set up Express server with TypeScript
  • task-002: Implement JWT authentication middleware
  • task-003: Create user registration endpoint
  • task-004: Create todo CRUD endpoints (scope: 5 files)
  • task-005: Add API integration tests
3

Tasks dispatch to workers

  • Tasks 1-3, 5 → Direct to workers (small scope)
  • Task 4 → Routes to subplanner (5 files exceeds threshold)
    • Subplanner decomposes into: task-004-sub-1, task-004-sub-2, etc.
    • Each subtask dispatches to a worker
All workers execute in parallel across isolated Modal sandboxes.
4

Workers complete and push branches

Each worker:
  1. Clones the target repository
  2. Creates a task-specific branch
  3. Uses Pi agent to implement changes
  4. Commits and pushes the branch
  5. Returns a handoff report with diff, concerns, and metrics
5

Merge queue processes branches

Branches merge sequentially:
worker/task-001 → main (merged)
worker/task-002 → main (merged)
worker/task-003 → main (conflict) → rebase → retry → merged
worker/task-004-sub-1 → main (merged)
...
6

Reconciler ensures health

After merges, reconciler runs:
npx tsc --noEmit  # Build check
npm test          # Test check
If failures detected → creates fix-001 task with high priority
7

Finalization phase

After all tasks complete:
  1. Drain merge queue completely
  2. Re-attempt unmerged branches
  3. Run final build + test sweep
  4. Report success or remaining issues

​
Key design principles

​
Ephemeral workers

Workers are completely stateless: 
# Each task spawns a fresh sandbox
sandbox = modal.create_sandbox(
  cpu=4,
  memory=8192,
  idle_timeout=300
)

# Worker lifecycle: create → execute → terminate
result = sandbox.run_task(task)
sandbox.terminate()
No persistent pool management, no session rollover complexity.

​
Git as source of truth

All state lives in Git:
  • Repository structure defines current state
  • Branches represent in-progress work
  • Commits create an audit trail
  • Main branch is the single source of truth
Longshot never performs destructive git operations (force push to main, hard reset main) unless explicitly requested. All worker branches are preserved on remote for manual recovery if needed.

​
Continuous conversation planning

The root planner maintains a continuous LLM session: 
// Initial plan
const prompt = buildInitialPrompt(request, repoState);
await session.prompt(prompt);
const tasks = parseTasks(session.getResponse());

// Follow-up planning after 3 tasks complete
const followUp = buildFollowUpPrompt(newHandoffs, repoState);
await session.prompt(followUp);
const moreTasks = parseTasks(session.getResponse());
The planner adapts based on worker handoffs, avoiding re-planning until meaningful new information arrives (minimum 3 handoffs).

​
System requirements

For end users (CLI):
  • Python 3.12+
  • Node.js 22+ (downloaded automatically by CLI)
  • Modal account (for cloud sandboxes)
  • LLM API endpoint (OpenAI-compatible)
For development (this repository):
  • Node.js 22+
  • pnpm
  • Python 3.12+
  • uv
  • Modal CLI (modal setup)

​
Next steps

Architecture deep dive

Explore the technical architecture and component interactions

Execution flow

Follow a request through the entire system lifecycle

Build docs developers (and LLMs) love

Get started for freeTalk to us