lazy-bird 0.1.0

Automate development projects with Claude Code - works with 18 frameworks

    🦜                                                      🦜
       _           _     ________  __     __
      | |         / \    |___  /   \ \   / /
      | |        / _ \      / /     \ \_/ /
      | |___    / ___ \    / /__     \   /
      |_____|  /_/   \_\  /_____|     |_|

       ____    ___   ____    ____
      | __ )  |_ _| |  _ \  |  _ \
      |  _ \   | |  | |_) | | | | |
      | |_) |  | |  |  _ <  | |_| |
      |____/  |___| |_| \_\ |____/
    💤                                                      💤

Automate ANY development project while you sleep 🦜💤

Your AI-powered development assistant that works 24/7

Works with: Godot, Unity, Python, Rust, Node.js, Django, React, and more!

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. One-command installation
curl -L https://raw.githubusercontent.com/yusyus/lazy-bird/main/wizard.sh | bash

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

# 3. Monitor progress
./wizard.sh --status

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

✨ 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

Phase 1: Single Agent (Start here)

• One task at a time, sequential processing
• 15-minute wizard setup, 8GB RAM
• Perfect for solo developers

Phase 0: Web UI (✅ Complete!)

• React + TypeScript dashboard
• System monitoring (CPU, RAM, disk)
• Project management (add/edit/remove)
• Service control (start/stop/restart)
• Task queue viewer with logs
• Dark mode support

Phase 1.1: Multi-Project (✅ Complete!)

• Single server manages 2-20+ projects simultaneously
• Add/remove/edit projects via CLI or Web UI
• Per-project configuration (test/build/lint commands)
• Sequential processing across all projects
• 8-10GB RAM recommended
• 26/26 tests passed

Phase 2: Multi-Agent (Planned)

• 2-3 agents working in parallel
• Test Server coordinates execution
• 16GB RAM recommended

Phase 3+: Remote access (VPN), CI/CD, enterprise features

💻 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

Usage

Creating Tasks

Create a GitHub/GitLab issue with detailed steps:

## Task Description
Add a health system to the player character

## Detailed Steps
1. Create res://player/health.gd with Health class
2. Add max_health (100) and current_health properties
3. Implement take_damage(amount) method
4. Implement heal(amount) method (max at max_health)
5. Add health_changed signal

## Acceptance Criteria
- [ ] Health class exists with all methods
- [ ] Tests pass
- [ ] Signal emits correctly

## Complexity
medium

Add the ready label and the system will pick it up within 60 seconds.

Monitoring Progress

# Check system status
./wizard.sh --status

# View logs
journalctl -u issue-watcher -f
journalctl -u godot-server -f

# Health check
./wizard.sh --health

Managing the System

./wizard.sh --status          # Current state
./wizard.sh --upgrade         # Move to next phase
./wizard.sh --health          # Run diagnostics
./wizard.sh --repair          # Fix issues
./wizard.sh --weekly-review   # Progress report

Managing Multiple Projects (Phase 1.1+)

# List all configured projects
python3 scripts/project-manager.py list

# Add a new project to existing setup
./wizard.sh --add-project
# Or use CLI directly:
python3 scripts/project-manager.py add \
  --id "my-backend" \
  --name "My Backend API" \
  --type python \
  --path /path/to/backend \
  --repository https://github.com/user/backend \
  --test-command "pytest tests/"

# Show details for a specific project
python3 scripts/project-manager.py show --id "my-backend"

# Enable/disable a project
python3 scripts/project-manager.py enable --id "my-backend"
python3 scripts/project-manager.py disable --id "my-backend"

# Remove a project
python3 scripts/project-manager.py remove --id "my-backend"

# After adding/removing projects, restart services
systemctl --user restart issue-watcher

📋 Example Workflows

Game Developer (Godot)

# Morning routine (5 minutes)
gh issue create --template task --title "Add pause menu" --label "ready"
gh issue create --template task --title "Fix jump physics" --label "ready"
gh issue create --template task --title "Add sound effects" --label "ready"
# → Claude runs gdUnit4 tests, creates PRs

# Check at lunch (2 minutes)
gh pr list  # Review created PRs
gh pr review 123 --approve

# Evening (5 minutes)
git pull && godot --headless -s res://test_runner.gd
# Test merged changes in game

Web Developer (Django/Python)

# Morning
gh issue create --template task --title "Add JWT authentication" --label "ready"
gh issue create --template task --title "Optimize database queries" --label "ready"
# → Claude runs pytest, creates PRs

# Lunch break
gh pr list
gh pr review 45 --approve
# → Merged automatically

# Evening
git pull && python manage.py test
# All tests pass, deploy to staging

Systems Programmer (Rust)

# Morning
gh issue create --template task --title "Optimize hash function" --label "ready"
gh issue create --template task --title "Add memory pooling" --label "ready"
# → Claude runs cargo test, creates PRs

# Review later
gh pr list
gh pr diff 89  # Check performance improvements
gh pr review 89 --approve

# Deploy
git pull && cargo build --release

Frontend Developer (React)

# Morning
gh issue create --template task --title "Add dark mode toggle" --label "ready"
gh issue create --template task --title "Improve loading states" --label "ready"
# → Claude runs Jest tests, creates PRs

# Afternoon
gh pr list
gh pr review 67 --approve
# → CI/CD deploys to preview

# Check preview, merge to production

Multi-Project Developer (Phase 1.1+)

Scenario: Managing a game, backend, and frontend simultaneously

# Initial setup - configure 3 projects
./wizard.sh
# → Configure: my-game (Godot)
# → Add project: my-backend (Django)
# → Add project: my-frontend (React)

# Verify all projects configured
python3 scripts/project-manager.py list
# Shows:
# 1. [my-game] My Game (godot) - ✅ ENABLED
# 2. [my-backend] My Backend API (python) - ✅ ENABLED
# 3. [my-frontend] My Frontend (react) - ✅ ENABLED

# Morning - create issues across all projects
gh issue create --repo user/my-game --template task --title "Add boss fight" --label "ready"
gh issue create --repo user/my-backend --template task --title "Add WebSocket support" --label "ready"
gh issue create --repo user/my-frontend --template task --title "Add real-time notifications" --label "ready"

# → Issue watcher polls all 3 repositories
# → Creates tasks with project-specific context
# → Uses project-specific test commands:
#   - Godot: gdUnit4 tests
#   - Django: pytest tests/
#   - React: npm test

# Lunch - review PRs from all projects
gh pr list --repo user/my-game
gh pr list --repo user/my-backend
gh pr list --repo user/my-frontend

# Approve and merge
gh pr review 42 --repo user/my-game --approve
gh pr review 89 --repo user/my-backend --approve
gh pr review 15 --repo user/my-frontend --approve

# Later - add a new project
./wizard.sh --add-project
# → Configure: my-mobile (react-native)
systemctl --user restart issue-watcher

# Now monitoring 4 projects!

Project Structure

lazy_birtd/
├── wizard.sh                 # Main installation script
├── scripts/
│   ├── godot-server.py      # Test coordination server
│   ├── issue-watcher.py     # GitHub/GitLab issue monitor
│   ├── agent-runner.sh      # Claude Code agent launcher
│   ├── project-manager.py   # Multi-project CLI tool (Phase 1.1+)
│   └── wizard-multi-project.sh  # Multi-project wizard functions
├── tests/
│   └── phase0/              # Validation tests
├── Docs/
│   └── Design/              # Complete specifications
├── docker/
│   └── claude-agent/        # Containerized Claude environment
└── templates/               # Issue templates

Configuration:
~/.config/lazy_birtd/
├── config.yml              # Main config (supports projects array)
├── secrets/                # API tokens (chmod 700)
└── logs/                   # All logs

Documentation

• CLAUDE.md - Complete guide for developers
• Docs/Design/ - Detailed specifications
  • phase1.1-multi-project.md - Multi-project architecture (Phase 1.1)
  • wizard-complete-spec.md - Wizard architecture
  • godot-server-spec.md - Test coordination
  • claude-cli-reference.md - Correct CLI commands
  • issue-workflow.md - GitHub/GitLab integration
  • retry-logic.md - Test failure handling
  • security-baseline.md - Security guidelines
  • phase0-validation.md - Pre-implementation testing

Key Concepts

Godot Server

HTTP API that queues and executes Godot tests sequentially, preventing conflicts when multiple agents need to run tests.

Claude Agent 1 ──┐
Claude Agent 2 ──┼──> Godot Server → Single Godot Process
Claude Agent 3 ──┘

Issue-Driven Tasks

Tasks are defined as GitHub/GitLab issues, not files. This provides:

• Mobile-friendly interface
• Permanent history
• Rich formatting (markdown, code blocks)
• Native PR linking

Test Retry Logic

If tests fail, Claude gets the error message and tries to fix it. Default: 3 retries (4 total attempts). Success rate: ~90-95%.

Git Worktrees

Each task gets its own isolated git worktree, preventing conflicts and allowing easy cleanup.

Security

Critical: Follow security guidelines in Docs/Design/security-baseline.md

• Secrets stored in ~/.config/lazy_birtd/secrets/ (chmod 600)
• Claude agents run in Docker containers
• Services bind to localhost or VPN only
• API tokens never committed to git
• Regular secret rotation (90 days)

Cost Estimate

• Phase 1: $50-100/month (Claude API)
• Phase 2-3: $100-150/month
• Phase 4+: $150-300/month

Budget limits and alerts included to prevent surprises.

Troubleshooting

Tasks not being processed

# Check issue watcher
systemctl status issue-watcher

# Verify API token
./tests/phase0/test-api-access.sh

# Check for issues with "ready" label
gh issue list --label "ready"

Tests failing

# Check Godot Server
systemctl status godot-server

# View test logs
cat /var/lib/lazy_birtd/tests/latest/output.log

# Test gdUnit4
godot --headless -s addons/gdUnit4/bin/GdUnitCmdTool.gd --help

General issues

# Run wizard diagnostics
./wizard.sh --health

# Auto-repair common problems
./wizard.sh --repair

# Check all logs
journalctl -u godot-server -f
journalctl -u issue-watcher -f

❓ FAQ

Q: Does this really work? A: The architecture is sound, but relies on Claude Code CLI working in headless mode. Run Phase 0 validation first to verify.

Q: What frameworks are supported? A: 15+ frameworks out-of-the-box: Godot, Unity, Unreal, Bevy, Django, Flask, FastAPI, Express, React, Vue, Angular, Svelte, Python, Rust, Node.js, Go, C/C++, Java, and more. Choose "Custom" during setup for any framework with command-line tests.

Q: How do I add a new framework? A: Select "Custom" during wizard setup and specify your test commands manually. For example, if you use pytest-cov: test_command: "pytest --cov=src". Any command-line test runner works!

Q: Is it safe? A: Yes, with proper setup. Claude runs in Docker containers, uses git worktrees, and has permission restrictions. Follow security baseline.

Q: How much does it cost? A: Claude API costs vary. Expect $50-300/month depending on usage. Budget limits prevent overages.

Q: Can I use it with game engines besides Godot? A: Yes! Unity, Unreal, and Bevy are supported via presets. During setup, select "Game Engine" and choose your engine. The wizard configures the appropriate test runner automatically.

Q: Does it work on Windows? A: Yes, via WSL2. Native Windows support is experimental.

Q: What if Claude breaks something? A: Tests catch most issues. Changes are in isolated worktrees and PRs for review. Nothing merges without approval.

Roadmap

Current Status: Phase 1.1 Complete - Multi-Project Support! 🎉

Phase 0 (Complete):

• ✅ Complete specification
• ✅ Validation framework
• ✅ Implementation (validate-claude.sh, validate-godot.sh, test-worktree.sh)

Phase 1 (Complete):

• ✅ Setup wizard (wizard.sh with 8-question flow)
• ✅ Single agent automation (agent-runner.sh)
• ✅ Issue watcher (issue-watcher.py with label workflow)
• ✅ Systemd service integration
• ✅ Status and health monitoring (--status, --health commands)

Phase 1.1 (Complete - NEW!):

• ✅ Multi-project configuration schema (projects array)
• ✅ Project-aware issue watcher with per-project monitoring
• ✅ Project-specific task execution (test/build/lint commands)
• ✅ CLI project management tool (project-manager.py)
• ✅ Wizard enhancement with --add-project command
• ✅ Comprehensive testing (26/26 tests passed)

Phase 2 (Week 2-3):

• Multi-agent scheduler
• Enhanced monitoring
• Remote access (VPN)

Future:

• CI/CD integration
• Visual test recording
• Team collaboration features
• Cost optimization

Contributing

Contributions welcome! Please:

1. Read CLAUDE.md first
2. Check Docs/Design/ for specifications
3. Run Phase 0 validation
4. Submit PRs with tests

License

MIT License - see LICENSE file.

🙏 Acknowledgments

• Built with Claude Code
• Supports Godot Engine, Unity, Django, React, Rust, and many more
• Framework test runners: gdUnit4, pytest, Jest, cargo test, and more

Support

• Documentation: CLAUDE.md and Docs/Design/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ☕ and 🤖 for developers who'd rather be creating than debugging

⭐ Star this repo if Lazy_Bird saves you time!

    🦜 Fly lazy, code smart

Status: Phase 1.1 Complete ✅ | Multi-Project Support ✅ | Multi-Framework Support ✅ | Production Ready | Start Automating Today!