Skip to main content
This guide walks you through building a complete project with Longshot from start to finish.

​
Project Overview

We’ll build a REST API for a todo application with the following features:
  • CRUD operations for todos
  • User authentication
  • Database persistence
  • API documentation

​
Prerequisites

Before starting, ensure you have:
  • Longshot installed (installation guide)
  • Modal account configured (modal setup)
  • A GitHub repository with push access
  • LLM API credentials (OpenAI, Anthropic, or compatible)

​
Step-by-Step Guide

1

Create a specification file

Create a SPEC.md file in your repository describing what you want to build:
SPEC.md
# Todo API Specification

Build a RESTful API for a todo application with the following requirements:

## Features
- User registration and authentication (JWT)
- CRUD operations for todos
- Each todo has: title, description, status (pending/completed), due date
- Users can only access their own todos
- API documentation with OpenAPI/Swagger

## Technical Requirements
- Framework: FastAPI (Python) or Express (Node.js)
- Database: PostgreSQL with SQLAlchemy/Prisma ORM
- Authentication: JWT tokens
- Validation: Pydantic/Zod schemas
- Testing: pytest/jest with >80% coverage
- Docker: Dockerfile and docker-compose.yml

## API Endpoints
- POST /auth/register - Register new user
- POST /auth/login - Login and get JWT token
- GET /todos - List all todos for authenticated user
- POST /todos - Create new todo
- GET /todos/{id} - Get specific todo
- PUT /todos/{id} - Update todo
- DELETE /todos/{id} - Delete todo
2

Configure environment

Create a .env file with your configuration:
.env
# LLM Configuration
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-your-api-key
LLM_MODEL=gpt-4o

# Git Configuration
GIT_REPO_URL=https://github.com/your-org/todo-api.git
GIT_TOKEN=ghp_your-github-token
GIT_MAIN_BRANCH=main

# Worker Configuration
MAX_WORKERS=20
WORKER_TIMEOUT=1800

# Orchestrator
MERGE_STRATEGY=rebase
FINALIZATION_ENABLED=true
3

Run Longshot with the dashboard

Execute Longshot with the Rich TUI dashboard for real-time monitoring:
longshot "Build a todo API according to SPEC.md" --dashboard
This will:
  1. Parse your specification
  2. Create a task decomposition plan
  3. Spawn parallel workers in Modal sandboxes
  4. Execute tasks concurrently
  5. Merge results into your repository
  6. Run reconciliation to fix any issues
4

Monitor progress

The dashboard shows real-time metrics:
╭─ Longshot Dashboard ──────────────────────────────────────╮
│ Request: Build a todo API according to SPEC.md           │
│ Runtime: 0:12:34                                          │
├───────────────────────────────────────────────────────────┤
│ Workers:   15 active  │  8 pending                        │
│ Tasks:     23 done    │  12 in progress  │  3 pending    │
│ Merges:    18 merged  │  0 failed        │  1 conflict   │
│ Throughput: 92 commits/hr  │  234,567 tokens              │
├───────────────────────────────────────────────────────────┤
│ Recent Activity:                                          │
│ ✓ task-12: Implement user authentication                 │
│ ✓ task-15: Create database models                        │
│ ⚡ task-18: Add todo CRUD endpoints                       │
│ ⚡ task-21: Write API tests                               │
╰───────────────────────────────────────────────────────────╯
5

Review the results

After completion, Longshot displays a run summary:
✓ Orchestrator finished

═══ Run Summary ═══
  Duration:   15m 23s
  Tasks:      38 done / 0 failed / 38 total
  Merges:     35 merged / 0 failed / 2 conflicts
  Throughput: 148 commits/hr  |  456,789 tokens
  Log:        logs/run-2026-03-03T10-23-45.log
  Traces:     logs/traces-2026-03-03T10-23-45.jsonl
  LLM log:    logs/llm-2026-03-03T10-23-45.jsonl
6

Review and test the code

Clone or pull your repository to review the generated code:
git clone https://github.com/your-org/todo-api.git
cd todo-api

# Review the changes
git log --oneline -20

# Run tests
docker-compose up -d
pytest  # or npm test
Longshot creates well-structured commits with descriptive messages:
abc1234 Add API documentation with Swagger
def5678 Implement todo CRUD endpoints
ghi9012 Add user authentication with JWT
jkl3456 Create database models and migrations
mno7890 Initialize FastAPI project structure

​
Understanding Task Decomposition

Longshot’s root planner broke your specification into granular tasks:
  1. Project scaffolding - Initialize project structure
  2. Database setup - Models, migrations, connection
  3. Authentication - User model, JWT, registration/login
  4. Core features - Todo CRUD operations
  5. Validation - Request/response schemas
  6. Testing - Unit and integration tests
  7. Documentation - OpenAPI/Swagger specs
  8. Containerization - Dockerfile, docker-compose
  9. Finalization - Reconciler fixes any issues
Each task was executed in parallel in its own isolated Modal sandbox.

​
Handling Build Issues

If Longshot encounters build failures, the reconciler automatically:
  1. Detects issues - Monitors build health every 10 seconds (configurable)
  2. Analyzes failures - Examines test failures, linting errors, type errors
  3. Creates fix tasks - Spawns new workers to resolve issues
  4. Retries - Attempts fixes up to FINALIZATION_MAX_ATTEMPTS times

​
Manual Intervention

If the reconciler can’t fix an issue: 
# Review the detailed logs
cat logs/run-2026-03-03T10-23-45.log

# Check LLM requests/responses
cat logs/llm-2026-03-03T10-23-45.jsonl | jq .

# Run Longshot again with a more specific request
longshot "Fix the authentication tests that are failing"

​
Advanced Options

​
Reset Before Running

Reset your repository to the initial commit before running: 
longshot "Build todo API according to SPEC.md" --reset
This will discard all uncommitted changes and reset to the first commit in the repository.

​
Debug Mode

Enable verbose logging for troubleshooting: 
longshot "Build todo API according to SPEC.md" --debug
This sets LOG_LEVEL=debug and shows:
  • Detailed task decomposition
  • Worker dispatch and completion events
  • Merge queue operations
  • LLM request/response summaries

​
Iterative Development

After the initial build, make incremental changes: 
# Add a new feature
longshot "Add email notifications when a todo is due"

# Fix a bug
longshot "Fix the issue where completed todos show as pending"

# Refactor
longshot "Refactor the authentication code to use a separate service layer"
Longshot works on top of your existing codebase, making incremental changes.

​
Best Practices

The more detail you provide in your specification, the better results you’ll get:
  • List all features and requirements explicitly
  • Specify technical choices (frameworks, libraries, patterns)
  • Include non-functional requirements (testing, performance, security)
  • Provide examples of expected behavior
For your first project:
  • Start with a well-defined, medium-sized project (not too large)
  • Use familiar tech stacks
  • Provide clear acceptance criteria
  • Review results before scaling up
Keep an eye on costs:
  • LLM API usage (check token counts in run summary)
  • Modal compute costs (reduce MAX_WORKERS if needed)
  • Adjust SANDBOX_CPU_CORES and SANDBOX_MEMORY_MB based on your workload
Treat Longshot output as a first draft:
  • Review all generated code
  • Run tests and verify functionality
  • Make manual adjustments as needed
  • Use Longshot again for improvements: “Refactor X to improve Y”

​
Troubleshooting

​
Common Issues

If workers frequently timeout:
.env
# Increase worker timeout (default: 1800 seconds)
WORKER_TIMEOUT=3600

# Reduce task complexity by breaking down the request
# Or increase sandbox resources
SANDBOX_CPU_CORES=8
SANDBOX_MEMORY_MB=16384
If you encounter frequent merge conflicts:
.env
# Try a different merge strategy
MERGE_STRATEGY=merge-commit  # instead of rebase

# Reduce parallelism to minimize conflicts
MAX_WORKERS=10
If you hit rate limits:
.env
# Reduce parallel workers
MAX_WORKERS=10

# Or configure multiple endpoints for load balancing
LLM_ENDPOINTS=[{"baseUrl":"https://api.openai.com/v1","apiKey":"sk-1"},{"baseUrl":"https://api.anthropic.com/v1","apiKey":"sk-ant-2"}]

​
Next Steps

Architecture

Learn how Longshot works under the hood

CLI Reference

Explore all CLI options and commands

Build docs developers (and LLMs) love

Get started for freeTalk to us