# 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.