lazy-bird

Quick Start • Features • Installation • Docs • Architecture

🎯 What is Lazy_Bird?

Lazy_Bird is a progressive automation system that lets Claude Code work on your development projects autonomously—game engines, backends, frontends, or any codebase. Create GitHub Issues in the morning, review Pull Requests at lunch, and merge completed features in the evening—all while you focus on creative work or simply relax.

Morning (7 AM)          Work Hours                 Lunch (12 PM)         Evening (6 PM)
──────────────          ──────────────             ─────────────         ─────────────
Create Issues      →    Claude implements     →    Review PRs       →    Merge & Ship
Add "ready" label       Runs tests automatically   Approve changes       Plan tomorrow
Go to work             Creates PRs if passing      Back to work          Enjoy life

The result? You save 20-100 hours per month on repetitive development tasks.

📦 Supported Frameworks

Lazy_Bird works with any project type through framework presets. During setup, simply select your framework and the system configures the right test commands automatically.

Game Engines

• Godot - GDScript/C#, gdUnit4 testing
• Unity - C#, NUnit/Unity Test Framework
• Unreal - C++/Blueprint, automation tests
• Bevy - Rust game engine, cargo test

Backend Frameworks

• Django - Python web framework, python manage.py test
• Flask - Python micro-framework, pytest
• FastAPI - Modern Python API, pytest
• Express - Node.js web framework, Jest/Mocha
• Rails - Ruby web framework, RSpec

Frontend Frameworks

• React - JavaScript/TypeScript, Jest/RTL
• Vue - JavaScript/TypeScript, Vitest
• Angular - TypeScript, Jasmine/Karma
• Svelte - JavaScript/TypeScript, Vitest

Programming Languages (General)

• Python - pytest, unittest, any test framework
• Rust - cargo test, cargo-nextest
• Node.js - npm test, Jest, Mocha, Vitest
• Go - go test, testify
• C/C++ - make test, CTest, CMake
• Java - JUnit, Maven, Gradle

Custom Projects

Don't see your framework? Choose "Custom" during setup and specify your test commands manually. Lazy_Bird supports any framework with a command-line test runner!

🚀 Quick Start

# 1. Install via pip (recommended)
pip install lazy-bird

# 2. Run setup wizard
lazy-bird setup

# 3. Create your first automated task
gh issue create --template task \
  --title "[Task]: Add player health system" \
  --label "ready"

# 4. Monitor progress
lazy-bird status

That's it! The system will pick up your issue, implement the feature, run tests, and create a PR—all automatically.

🎉 v2.0 Highlights

Lazy_Bird v2.0 represents a complete rewrite into a production-ready microservice architecture:

✅ All 70 Core Issues Completed

• FastAPI microservice architecture with async/await
• PostgreSQL database with complete JSONB support
• Celery distributed task queue with Redis
• 8 production-ready database models
• 30+ REST API endpoints
• Comprehensive E2E test coverage

🧪 Fully Tested & Validated

• End-to-end test validates complete workflow
• PostgreSQL schema fully validated
• 5 PostgreSQL compatibility issues discovered and fixed during testing
• Unit and integration test coverage
• Production-ready status confirmed

🚀 Ready for Deployment

• Docker and Docker Compose support
• Systemd service integration
• Multi-framework support (18+ frameworks)
• Intelligent task selection with cost controls
• Per-project concurrency limits
• Real-time web dashboard

✨ Features

• 🤖 Autonomous Development - Claude Code works while you're away
• 🎯 Multi-Framework Support - Works with 18 frameworks out-of-the-box
• 🗂️ Multi-Project Management - Monitor 2-20+ projects from a single server
• 🖥️ Web Dashboard - React + TypeScript UI for monitoring and management (Phase 0 complete!)
• 📦 Easy Installation - Available via pip/UV, ready in 5 minutes
• 🧪 Automated Testing - Runs framework tests, retries on failure
• 🌿 Safe Git Workflow - Isolated worktrees, automatic PRs
• 📊 Progress Monitoring - Real-time system stats, task queue viewer
• 🔐 Security First - Secret management, containerized execution
• 📈 Progressive Scaling - Start simple (1 agent), scale to multiple

How It Works

Morning (7-8am)          Work Hours                Lunch (12pm)        Evening (6pm)
─────────────────       ──────────────            ─────────────       ──────────────
Create GitHub Issues → Claude processes tasks  →  Review PRs      →  Merge & test
Add "ready" label       Runs tests automatically   Approve/comment     Deploy builds
Go to work              Creates PRs if passing     Back to work        Plan tomorrow

Architecture

v2.0 - Complete Microservice Architecture (✅ Production Ready!)

Lazy_Bird v2.0 is a full-featured FastAPI microservice architecture with:

Core Engine:

• FastAPI REST API with async/await
• PostgreSQL database with JSONB support
• SQLAlchemy ORM with Alembic migrations
• Celery distributed task queue with Redis
• Intelligent task selection with cost controls
• Per-project concurrency limits
• Daily cost limit enforcement

Web Dashboard:

• React + TypeScript single-page application
• Real-time system monitoring (CPU, RAM, disk)
• Project management (CRUD operations)
• Task queue viewer with execution logs
• Service control (start/stop/restart systemd services)
• Dark mode support
• Responsive design

Multi-Framework Support:

• 18+ frameworks out-of-the-box (Godot, Unity, Python, Rust, React, Django, etc.)
• Framework presets with auto-configuration
• Custom framework support
• Per-project test/build/lint commands

Database Schema:

• 8 production-ready tables (Projects, FrameworkPresets, Tasks, APIKeys, etc.)
• Complete PostgreSQL JSONB support
• Alembic migration system
• Full E2E test coverage

Testing & Validation:

• Comprehensive E2E test suite
• PostgreSQL schema validation
• Complete workflow testing (database → execution → PRs)
• Unit and integration test coverage

Deployment:

• Docker and Docker Compose support
• Systemd service integration
• Multi-project monitoring from single server
• Production-ready configuration

💻 Requirements

Universal Requirements:

• Linux (Ubuntu 20.04+, Arch, Manjaro, etc.) or Windows WSL2
• Claude Code CLI
• GitHub or GitLab account
• 8GB RAM minimum, 16GB recommended

Framework-Specific:

• Game Engines: Godot 4.2+, Unity 2021+, Unreal 5+, etc.
• Python: Python 3.8+, pip
• Rust: Rust 1.70+, cargo
• Node.js: Node.js 16+, npm
• Or any framework with command-line test runner

Installation

Quick Install (Recommended)

# Option 1: Install via pip (easiest)
pip install lazy-bird

# Then run setup wizard
lazy-bird setup

Alternative: One-Command Script

curl -L https://raw.githubusercontent.com/yusyus/lazy_birtd/main/wizard.sh | bash

Manual Install from Source

# Clone repository
git clone https://github.com/yusufkaraaslan/lazy-bird.git
cd lazy-bird

# Option A: Install as package
pip install -e .
lazy-bird setup

# Option B: Run wizard directly
# Run Phase 0 validation (required)
./tests/phase0/validate-all.sh /path/to/your/project --type <framework>

# Examples:
./tests/phase0/validate-all.sh /path/to/your/project --type godot
./tests/phase0/validate-all.sh /path/to/your/project --type python
./tests/phase0/validate-all.sh /path/to/your/project --type rust

# If validation passes, run wizard
./wizard.sh

The wizard will:

• Ask for your project type (Godot, Python, Rust, etc.)
• Detect your system capabilities
• Ask 8 simple questions
• Load framework preset automatically
• Install appropriate phase
• Configure issue watcher
• Create issue templates
• Validate everything works

Usa