ableton-mcp-ai/ralph/README.md

Ralph

Ralph is a local swarm runner for this Ableton MCP project.

It is built for the stack that already exists on this machine:

• codex authenticated via app login
• claude -p routed to Anthropic-compatible providers
• Windows native PowerShell
• this repository as the shared source of truth

Design

Ralph does not try to make every model edit the same tree at once.

The default flow is:

1. create a task pack in ralph/tasks/current/
2. create a dedicated implementer worktree
3. run one implementer model against that worktree
4. run multiple reviewers against the resulting diff
5. run codex exec resume against the persistent Codex master session
6. optionally run a fix pass in the same implementer worktree
7. leave a run folder with prompts, outputs, reviews and diffs

Default roles

• Implementer: opencode_glm5
• Reviewer 1: opencode_qwen3coder_plus
• Reviewer 2: opencode_glm47
• Codex master: persistent session reviewer and sprint writer

Important safety rule

Ralph does not auto-merge into the main working tree.

It creates a worktree under ralph/worktrees/ and leaves the result there for review or manual cherry-pick.

Local config

Sensitive config is stored in:

• ralph/config/providers.local.json
• ralph/config/codex.local.json

Both are gitignored.

Quick start

Smoke test providers:

powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Test-RalphProviders.ps1

Smoke test Codex master:

powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Test-RalphCodex.ps1

Run one autonomous pass on the current task pack:

powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Start-RalphAutopilot.ps1

Start the localhost dashboard:

powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Start-RalphDashboard.ps1

Default URL:

http://127.0.0.1:8765

Dry run only:

powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Start-RalphAutopilot.ps1 -DryRun

Submit a single markdown task into the inbox:

powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Submit-RalphTask.ps1 `
  -SourceFile .\docs\SPRINT_v0.1.40_NEXT_GLM_OPEN_PROJECT_EDITING_AND_COHERENCE.md

Run the inbox daemon in the foreground:

powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Start-RalphInboxDaemon.ps1

Run the inbox daemon in the background:

powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Start-RalphInboxBackground.ps1

Stop the inbox daemon:

powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Stop-RalphInboxDaemon.ps1

Check daemon and queue status:

powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Get-RalphStatus.ps1

Install the inbox daemon as a Windows Scheduled Task:

powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Install-RalphScheduledTask.ps1

Run Codex master review only:

powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Invoke-CodexMaster.ps1 `
  -PromptFile .\ralph\tasks\current\TASK.md `
  -OutputFile .\ralph\state\codex_master_manual_review.md

Task pack

The current swarm task lives here:

• ralph/tasks/current/TASK.md
• ralph/tasks/current/ACCEPTANCE.md
• ralph/tasks/current/CONTEXT.md

Update those files before each autonomous run.

Codex master session

Ralph is configured to reuse the persistent Codex session supplied by the user.

That gives Codex memory across reviews without needing an OpenAI API key.

24/7 inbox mode

Ralph can now run as a local queue processor:

• drop a single .md into ralph/tasks/inbox/
• the daemon converts it into a task pack automatically
• the implementer runs in an isolated worktree
• the configured reviewers run next
• Codex master performs the final review through codex exec resume
• the run only counts as complete if Codex final verdict is pass

The queue folders are:

• ralph/tasks/inbox
• ralph/tasks/processing
• ralph/tasks/completed
• ralph/tasks/failed

Recommended default routing:

• implementer: opencode_glm5
• reviewers: opencode_qwen3coder_plus, opencode_glm47
• final reviewer: persistent Codex master session

Notes

• If a token was ever exposed outside this machine, rotate it.
• If Ableton runtime work is involved, the swarm still has to validate against the real Live session and logs.
• Provider quality is not treated as equal. glm-5.1 remains the preferred reviewer.
• The dashboard reads local state files and recent run folders. It does not execute runs on its own.