177 lines
4.5 KiB
Markdown
177 lines
4.5 KiB
Markdown
# 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
|
|
powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Test-RalphProviders.ps1
|
|
```
|
|
|
|
Smoke test Codex master:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Test-RalphCodex.ps1
|
|
```
|
|
|
|
Run one autonomous pass on the current task pack:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Start-RalphAutopilot.ps1
|
|
```
|
|
|
|
Start the localhost dashboard:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Start-RalphDashboard.ps1
|
|
```
|
|
|
|
Default URL:
|
|
|
|
```text
|
|
http://127.0.0.1:8765
|
|
```
|
|
|
|
Dry run only:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Start-RalphAutopilot.ps1 -DryRun
|
|
```
|
|
|
|
Submit a single markdown task into the inbox:
|
|
|
|
```powershell
|
|
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
|
|
powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Start-RalphInboxDaemon.ps1
|
|
```
|
|
|
|
Run the inbox daemon in the background:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Start-RalphInboxBackground.ps1
|
|
```
|
|
|
|
Stop the inbox daemon:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Stop-RalphInboxDaemon.ps1
|
|
```
|
|
|
|
Check daemon and queue status:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Get-RalphStatus.ps1
|
|
```
|
|
|
|
Install the inbox daemon as a Windows Scheduled Task:
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\ralph\scripts\Install-RalphScheduledTask.ps1
|
|
```
|
|
|
|
Run Codex master review only:
|
|
|
|
```powershell
|
|
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.
|