How Melliza Works¶

Melliza is an autonomous coding agent that transforms your requirements into working code, without constant back-and-forth prompting.

Tip

For the motivation behind Melliza and a deeper exploration of autonomous coding agents, read the blog post: Introducing Melliza: Autonomous PRD Agent

The Core Concept¶

Traditional AI coding assistants hit a wall: the context window. As your conversation grows, the AI loses track of earlier details, makes contradictory decisions, or simply runs out of space. Long coding sessions become unwieldy.

Melliza takes a different approach using a Ralph Wiggum loop: each iteration starts fresh, but nothing is forgotten.

You describe what you want to build as a series of user stories. Melliza works through them one at a time, spawning a new Gemini session for each. Between iterations, Melliza persists state to a progress.md file: what was built, which files changed, patterns discovered, and context for future work. The next iteration loads this history, giving Gemini everything it needs without the baggage of a bloated conversation.

Running melliza opens a TUI dashboard where you can review your project, then press s to start the loop.

The Execution Loop¶

Melliza works through your stories methodically. Each iteration focuses on a single story:

                ┌───────────────────────────────────────┐
                │                                       │
                ▼                                       │
        ┌──────────────┐                                │
        │  Pick Story  │                                │
        │  (next todo) │                                │
        └──────┬───────┘                                │
               │                                        │
               ▼                                        │
        ┌──────────────┐                                │
        │ Invoke Gemini│                                │
        │  with prompt │                                │
        └──────┬───────┘                                │
               │                                        │
               ▼                                        │
        ┌──────────────┐                                │
        │    Gemini    │                                │
        │ codes & tests│                                │
        └──────┬───────┘                                │
               │                                        │
               ▼                                        │
        ┌──────────────┐                                │
        │    Commit    │                                │
        │   changes    │                                │
        └──────┬───────┘                                │
               │                                        │
               ▼                                        │
        ┌──────────────┐           more stories         │
        │ Mark Complete├────────────────────────────────┘
        └──────┬───────┘
               │ all done
               ▼
           ✓ Finished

Here's what happens in each step:

Pick Story: Melliza finds the highest-priority incomplete story
Invoke Gemini: Constructs a prompt with the story details and project context, then spawns Gemini CLI
Gemini CLIs: Gemini reads files, writes code, runs tests, and fixes issues until the story is complete
Commit: Gemini commits the changes with a message like feat: [US-001] - Feature Title
Mark Complete: Melliza updates the project state and records progress
Repeat: If more stories remain, the loop continues

This isolation is intentional. If something breaks, you know exactly which story caused it. Each commit represents one complete feature.

Conventional Commits¶

Every completed story results in a well-formed commit:

feat: [US-003] - Add user authentication

- Implemented login/logout endpoints
- Added JWT token validation
- Created auth middleware

Your git history becomes a timeline of features, matching 1:1 with your stories.

Progress Tracking¶

The progress.md file is what makes fresh context windows possible. After every iteration, Gemini appends:

What was implemented
Which files changed
Learnings for future iterations (patterns discovered, gotchas, context)

When the next iteration starts, Gemini reads this file and immediately understands the project's history, without needing thousands of tokens of prior conversation. This gives you the benefits of long-running context (consistency, institutional memory) without the downsides (context overflow, degraded performance).

Worktree Isolation for Parallel PRDs¶

When running multiple PRDs simultaneously, each PRD can work in its own isolated git worktree. This prevents parallel Gemini instances from conflicting over files, producing interleaved commits, or stepping on each other's branches.

When you start a PRD, Melliza offers to create a worktree: - A new branch is created (e.g., melliza/auth-system) from your default branch - A worktree is set up at .melliza/worktrees/<prd-name>/ - Any configured setup command runs automatically (e.g., npm install)

Each worktree is a full checkout of your project, so Gemini can read, write, and run tests independently. When the PRD completes, you can merge the branch back, push it to a remote, or have Melliza automatically create a pull request.

The TUI shows branch and directory information throughout: - Tab bar: Branch name next to each PRD tab - Dashboard header: Current branch and working directory - PRD picker: Branch and worktree path for each PRD

Staying in Control¶

Autonomous doesn't mean unattended. The TUI lets you:

Start / Pause / Stop: Press s to start, p to pause after the current story, x to stop immediately
Review diffs: Press d to see the commit diff for the selected story
Edit the PRD: Press e to open the current PRD in Gemini CLI for refinement
Switch projects: Press l to list PRDs, n to create a new one, or 1-9 to jump directly
Resume anytime: Walk away, come back, press s. Melliza picks up where you left off
Merge branches: Press m in the picker to merge a completed branch
Clean worktrees: Press c in the picker to remove a worktree and optionally delete the branch
Configure settings: Press , to open the Settings overlay