Getting Started

Get up and running with YOLO Developer in under 5 minutes.

Prerequisites
Step 1: Install YOLO Developer
Step 2: Configure API Keys
Optional: Integrate with External CLI Tools
Step 3: Initialize a Project
Brownfield Option: Scan an Existing Project
Step 4: Create Requirements
Step 5: Seed Requirements
Step 6: Run Autonomous Development
Step 7: Review Results
Next Steps
Troubleshooting

Prerequisites

Before installing YOLO Developer, ensure you have:

Python 3.10 - 3.13 - Check with python --version
uv package manager - Install from astral.sh/uv
API Key - OpenAI or Anthropic API key for LLM access
GitHub CLI (optional) - Install gh and run gh auth login for GitHub automation commands

Step 1: Install YOLO Developer

# Clone the repository
git clone https://github.com/bbengt1/yolo-developer.git
cd yolo-developer

# Install dependencies
uv sync

# Verify installation
uv run yolo --help

If uv picks the wrong interpreter, force it explicitly:

uv run --python 3.13 yolo --help

Expected output:

Usage: yolo [OPTIONS] COMMAND [ARGS]...

  YOLO Developer - Autonomous AI Development System

Options:
  --version  Show version and exit.
  --help     Show this message and exit.

Commands:
  chat    Start interactive chat or run one-shot prompts.
  config  Manage project configuration.
  init    Initialize a new YOLO project.
  logs    View agent activity logs.
  mcp     Start MCP server for Claude Code.
  run     Execute autonomous development sprint.
  seed    Seed requirements for development.
  status  Display current sprint status.
  tune    Adjust quality thresholds.

To launch the interactive interface directly:

uv run yolo

Step 2: Configure API Keys

YOLO Developer requires an LLM API key. Set it via environment variable:

Never put API keys in configuration files. Always use environment variables. For local development only, you may set YOLO_ALLOW_YAML_SECRETS=1 to allow keys in yolo.yaml (do not commit secrets).

OpenAI

export YOLO_LLM__OPENAI__API_KEY=sk-proj-...

Anthropic

export YOLO_LLM__ANTHROPIC_API_KEY=sk-ant-api03-...

Verify Configuration

uv run yolo config show

Expected output (abbreviated):

project_name: my-project
llm:
  provider: auto
  cheap_model: gpt-5.2-instant
  premium_model: claude-sonnet-4-20250514
  best_model: claude-opus-4-5-20251101
  openai_api_key: "**********"
  anthropic_api_key: "**********"
  openai:
    code_model: gpt-5.2-pro
  hybrid:
    enabled: false
quality:
  test_coverage_threshold: 0.8
  gate_pass_threshold: 0.7

Optional: Integrate with External CLI Tools

Configure MCP clients (Codex CLI, Claude Code, Cursor, VS Code) automatically:

uv run yolo integrate claude-code

Use --dry-run to preview or --config-path to target a custom config file.

Step 3: Initialize a Project

Navigate to your project directory and initialize:

cd /path/to/your/project
uv run yolo init

Interactive output:

Initializing YOLO Developer project...

? Project name: my-awesome-api
? Primary language: Python
? Test framework: pytest
? Include CI/CD templates? Yes

Creating configuration...
  ✓ Created yolo.yaml
  ✓ Created .yolo/ directory
  ✓ Initialized memory store

Project initialized successfully!

Next steps:
  1. Review yolo.yaml configuration
  2. Create a requirements document
  3. Run: yolo seed <requirements-file>

This creates:

yolo.yaml - Project configuration
.yolo/ - Memory and cache directory
.yolo/memory/ - ChromaDB vector storage

Brownfield Option: Scan an Existing Project

If you are adding YOLO Developer to an existing repository:

cd /path/to/existing/project
uv run yolo init --brownfield

To scan without changing the repo:

uv run yolo init --brownfield --scan-only

YOLO will generate .yolo/project-context.yaml to capture detected language, frameworks, structure, and conventions for the agents.

Step 4: Create Requirements

Create a requirements document. YOLO Developer accepts Markdown or plain text:

requirements.md:

# User Management API

## Overview
Build a REST API for user management with authentication.

## Requirements

### Functional
- Users can register with email and password
- Users can login and receive JWT token
- Users can view and update their profile
- Admins can list and manage all users

### Non-Functional
- Response time < 200ms for all endpoints
- Support 1000 concurrent users
- 99.9% uptime SLA

### Constraints
- Must use PostgreSQL database
- Must follow OpenAPI 3.0 specification
- Must include rate limiting

Step 5: Seed Requirements

Feed your requirements to YOLO Developer:

uv run yolo seed requirements.md

Output:

Parsing requirements document...
  ✓ Parsed 4 functional requirements
  ✓ Parsed 3 non-functional requirements
  ✓ Parsed 3 constraints

Running validation...
  ✓ No ambiguities detected
  ✓ No contradictions found
  ✓ SOP constraints validated

Seed Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Requirements: 10 total
  Categories:
    - Functional: 4
    - Non-Functional: 3
    - Constraints: 3
  Quality Score: 0.92

Seed ID: seed_a1b2c3d4-e5f6-7890-abcd-ef1234567890

Ready to run: yolo run

Step 6: Run Autonomous Development

Start the autonomous development sprint:

uv run yolo run

Real-time output:

Starting autonomous development sprint...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[ANALYST] Analyzing requirements...
  → Crystallizing requirement: "Users can register with email and password"
  → Crystallizing requirement: "Users can login and receive JWT token"
  ✓ Crystallized 4 requirements into 6 detailed specifications

[PM] Generating user stories...
  → Creating story: "User Registration"
  → Creating story: "User Authentication"
  → Creating story: "Profile Management"
  → Creating story: "Admin User Management"
  ✓ Generated 8 user stories with acceptance criteria

[ARCHITECT] Designing system architecture...
  → Analyzing 12-Factor compliance
  → Generating ADR: "JWT Authentication Strategy"
  → Generating ADR: "Database Schema Design"
  → Evaluating quality attributes
  ✓ Created 3 ADRs, identified 2 technical risks

[DEV] Implementing stories...
  → Implementing: US-001 User Registration
    - Creating models/user.py
    - Creating routes/auth.py
    - Creating tests/test_auth.py
  ✓ Completed US-001 (3 files, 89% coverage)

[TEA] Validating test coverage...
  → Running test suite
  → Analyzing coverage gaps
  ✓ Coverage: 87% (threshold: 80%)

[SM] Sprint complete!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Sprint Summary:
  Duration: 12m 34s
  Stories Completed: 8/8
  Test Coverage: 87%
  Quality Gates: 4/4 passing
  Token Usage: 125,430 tokens ($1.23)

Artifacts generated:
  - 3 Architecture Decision Records
  - 8 User Stories with Acceptance Criteria
  - 24 Source Files
  - 45 Test Files
  - API Documentation (OpenAPI 3.0)

Step 7: Review Results

Check Status

uv run yolo status

View Logs

# All logs
uv run yolo logs

# Filter by agent
uv run yolo logs --agent dev

# Filter by time
uv run yolo logs --since 1h

Export Audit Trail

uv run yolo logs --export audit.json

Next Steps

Now that you have YOLO Developer running:

CLI Reference - Learn all available commands
Configuration Guide - Customize behavior
MCP Integration - Use with Claude Code
Architecture Deep Dive - Understand how it works

Troubleshooting

“API key not found”

Ensure your API key is set correctly:

echo $YOLO_LLM__OPENAI__API_KEY

“ChromaDB initialization failed”

Clear the memory directory and reinitialize:

rm -rf .yolo/memory
uv run yolo init --reinit

“Quality gate failed”

View the gate failure report:

uv run yolo status --gates

Adjust thresholds if needed:

uv run yolo tune --coverage 0.7