Melliza

Autonomous agent loop for the Gemini CLI
Turn your PRDs into working code, one story at a time.

---

v0.2.0 Released — Migrated to native viewport scrolling, added multi-line text input and confirmation dialogs in PRD creation, fixed nil pointer panics, and improved log viewer performance. See the release notes.

---

Melliza is an autonomous agent loop that orchestrates the Gemini CLI to work through user stories in a Product Requirements Document (PRD).

Built on the "Ralph Wiggum loop" pattern, Melliza breaks down complex project requirements into manageable tasks, invokes Gemini to implement them one by one, and maintains persistent progress tracking.

✨ Core Features

• 🤖 Autonomous Loop: Orchestrates Gemini CLI to work through user stories without manual intervention.
• 📄 PRD-Driven Development: Work directly from human-readable prd.md files.
• 📈 Persistent Progress: Progress is tracked in prd.json and progress.md, ensuring work can be resumed across sessions.
• 🖥️ TUI Dashboard: A real-time terminal user interface to monitor Gemini's progress, logs, and diffs.
• 🌿 Smart Worktrees: Automatically creates git branches or worktrees for each PRD to keep your main workspace clean.
• ✅ Test-First + Auto-Commit: Gemini follows test-first TDD (red → green → refactor), runs your project's checks, and commits changes automatically.
• 🖼️ Visual Verification: For UI changes, Melliza requires screenshot-based confirmation (or an explicit environment limitation note).

🚀 Quick Start

1. Install Melliza

# Via Homebrew
brew install lvcoi/melliza/melliza

# Or via install script
curl -fsSL https://raw.githubusercontent.com/lvcoi/melliza/main/install.sh | bash

2. Prerequisites

Ensure you have the Gemini CLI installed and your GEMINI_API_KEY configured.

3. Usage

# Create a new PRD (launches interactive session)
melliza new my-project

# Run the loop
melliza my-project

⚙️ How it Works

Melliza follows a simple, repeatable cycle:

1. Plan: Identify the next incomplete story in prd.json.
2. Execute: Invoke Gemini CLI with a specialized system prompt and the current story context.
3. Monitor: Parse Gemini's stream-json output to update the TUI and progress files.
4. Finalize: Once Gemini completes the story, Melliza moves to the next one.

📚 Documentation

Full documentation is available at lvcoi.github.io/melliza.

📖 Key Documentation

• Installation Guide
• Quick Start
• How it Works
• PRD Format

🛠️ Development

make build  # Build the binary
make test   # Run all tests
make run    # Launch the TUI (dev mode)

📄 License

This project is licensed under the MIT License.