ralphception 0.1.1

Codex-native orchestration runtime.

Ralphception

ralphception is a Codex-native agent orchestrator for "Ralph loops of Ralph loops":

• one outer run per target repo
• child runs for spec extraction, planning, execution, merge, and audit
• parallel child work where it is safe
• repeated audit/reopen cycles until blocking gaps are gone

The core runtime is implemented and tested. The current repo is best understood as an alpha runtime with real storage, workflow, recovery, review, and dashboard layers, but not yet a fully polished one-command product UX.

Current Status

What is implemented today:

• repo-local .ralphception/ runtime state and config
• XDG-backed lease and resume state
• workflow engine, approvals, bundles, recovery, verification, audit, worktrees, and merge coordination
• one shared runtime supervisor with two frontends:
  • a Textual TUI launched by uv run ralphception
  • a traditional terminal frontend launched by uv run ralphception terminal
• interactive startup and review screens backed by the same shared runtime supervisor
• automatic first-child execution startup from the TUI launch path once an execution bundle is approved and a session backend is available
• long-running terminal execution that uses the same durable mission loop as the TUI
• end-to-end tests with deterministic fake Codex/session behavior

What is not fully polished yet:

• ralphception resume now resumes the current workspace root run in read or repair mode, but the top-level CLI still does not expose historical-run selection
• release automation / PyPI publishing / final uvx polish are still follow-on work

How To Think About It

There is one runtime and two frontends today:

flowchart TD
    A["Shared runtime supervisor"] --> B["Textual frontend"]
    A --> C["Terminal frontend"]
    B --> D["Startup / review / dashboard surfaces"]
    C --> E["Logs + focused prompts"]

The intended product flow is:

flowchart TD
    A["Seed prompt + optional source repos"] --> B["Startup / intake"]
    B --> C["Spec generation"]
    C --> D["Spec review"]
    D --> E["Plan / bundle generation"]
    E --> F["Bundle review"]
    F --> G["Execution child runs"]
    G --> H["Merge + verification"]
    H --> I["Audit loop"]
    I --> J{"Open P0/P1/P2?"}
    J -- yes --> E
    J -- no --> K["Done"]

The important distinction is that the runtime loop is now shared. The Textual and terminal entrypoints are different surfaces over the same durable mission state and the same execution/audit/reopen cycle.

Quick Start

Local development usage today:

mise run install
mise run run

Equivalent uv commands:

uv sync
uv run ralphception
uv run ralphception terminal

Once the package is published, the intended entrypoint is:

uvx ralphception

What Happens On Launch

uv run ralphception resolves the current workspace and does one of three things in the TUI frontend:

1. Startup mode if .ralphception/runs/run-root/startup.json does not exist.
2. Review mode if spec approval, execution-bundle approval, or blocked-run recovery is pending.
3. Dashboard mode otherwise.

uv run ralphception terminal resolves the same runtime state, but renders it as logs and prompts instead of panes.

The runtime always works inside the target repo and writes ephemeral runtime state under .ralphception/. That directory is intentionally disposable and should not be committed to git. When dashboard mode opens against an approved execution bundle with no existing child runs, the launch path still starts the first execution child run before rendering the dashboard.

How To Use It Today

1. Bootstrap a workspace

Run:

uv run ralphception

If the workspace has not been bootstrapped yet, the startup screen now prompts for:

• a seed prompt for the outer run
• optional source repository paths, one path per line

Submitting the form persists .ralphception/runs/run-root/startup.json, writes the intake artifact, and then launches the resolved runtime view for the workspace.

If you want the same top-level mission loop without opening Textual, use the terminal frontend:

uv run ralphception terminal \
  --seed-prompt "port parser" \
  --source-repo /path/to/source-repo \
  --approve-all

uv run ralphception headless ... remains as a compatibility alias during the transition.

Useful flags:

• --repo-root <path> to operate on another workspace
• --approve-all to auto-approve spec and execution-bundle review targets so the supervisor can run to terminal completion without a human
• --fake-session-manager to inject the deterministic fake Codex backend used by the test suite when you want to verify the full loop without a live session backend

Terminal execution requires either the codex CLI on your PATH or --fake-session-manager. uv sync only installs Ralphception's Python dependencies; the live session backend comes from the Codex CLI's app-server. If neither is available, uv run ralphception terminal ... now exits immediately with a backend error instead of falling back to dashboard mode.

The terminal frontend behaves as a long-running mission supervisor:

• bootstrap intake if needed
• generate or reuse spec and plan artifacts
• approve the spec and execution bundle when --approve-all is set
• create child worktrees, execute, verify, merge, and audit
• reopen execution automatically when audit leaves blocking P0/P1/P2 findings open
• exit only after terminal completion or failure

While the mission is running, the terminal frontend now streams readable high-level progress such as stage changes, turn start/completion, approvals, child-run creation, verification outcomes, merges, audit reopen decisions, and mission completion.

The durable mission-loop state for the root run lives at:

.ralphception/runs/run-root/headless-state.json

The default stage artifacts are:

.ralphception/specs/mission-spec.md
.ralphception/plans/mission-plan.md
.ralphception/plans/mission-plan.json
.ralphception/runs/<child-run-id>/handoff.json
.ralphception/runs/run-root/audit-findings.json

To monitor a running terminal mission, tail the root event log from another shell:

tail -f .ralphception/events/run-root.jsonl

1a. Bootstrap finisher helper

When you are using Ralphception to finish Ralphception itself, the helper-only loop state lives under:

.ralphception/bootstrapping/
|- finish-criteria.md
|- gaps.json
|- gaps.md
|- inputs.json
|- prompt.txt
`- iterations/

There is now a repo-root ralph.sh loop entrypoint. It repeatedly runs one bootstrap iteration at a time until the loop is done, stops for human review, or exits on failure:

./ralph.sh

It calls uv run python -m ralphception.bootstrap.runner --loop-once, refreshes the bootstrap prompt and command, launches a fresh codex exec iteration, and lets Python decide whether to continue, stop for review, or finish.

2. Understand what the runtime wrote

The workspace layout looks like this:

.ralphception/
|- config.toml
|- approvals/
|- events/
|- findings/
|- merge/
|- plans/
|- runs/
|- skills/
|- specs/
|- todos/
`- verification/

Important files early in the flow:

• .ralphception/config.toml The persisted runtime config.
• .ralphception/runs/run-root/startup.json The seed prompt and source repo capture.
• .ralphception/runs/run-root/intake.md The intake artifact written from the seed prompt.

3. Use the dashboard when the runtime reaches dashboard mode

The dashboard supports these slash commands:

• /help
• /model <name>
• /resume [repair]
• /status
• /artifacts
• /approve
• /retry
• /restart
• /replace
• /abort

Right now the dashboard is the main interactive surface that is actually wired. It now launches with recovery configured, and if the workspace already has an approved execution bundle the initial execution child run is scheduled before the dashboard renders.

4. Use review mode when review is pending

When the workspace has a pending spec review, execution-bundle approval, or recovery-eligible blocked run, uv run ralphception now opens an interactive review screen. It shows:

• the pending review and recovery targets for the workspace
• a details pane for the selected target
• a diff pane for spec or execution-bundle artifacts
• approve, resume, retry, restart, and replace actions when they apply

The Python controller surface still exists for scripting and tests. If you want to inspect the current target programmatically:

uv run python - <<'PY'
from pathlib import Path
from ralphception.app import resolve_runtime_view

launch = resolve_runtime_view(Path.cwd())
assert launch.review_controller is not None

target = launch.review_controller.current_target()
print(target)
print()
print(launch.review_controller.diff_current_target().rendered_text)
PY

Default Runtime Config

By default, Ralphception writes .ralphception/config.toml with:

• model: gpt-5.4
• reasoning: high
• latency profile: fast
• sandbox: danger-full-access
• approval policy: never
• worktrees for edit runs: enabled
• max parallel children: 4
• audit reopen priorities: P0, P1, P2

The dashboard /model command updates the persisted config.

How Resume Works

Repo-local state lives in .ralphception/, but authoritative lease state is stored in XDG state:

$XDG_STATE_HOME/ralphception/<workspace-hash>/lease.json

The recovery layer can:

• read durable event logs
• reconcile checkpoints
• refuse healthy foreign leases
• steal stale leases in repair mode
• retry, restart, or replace blocked runs

The top-level CLI now exposes the current workspace root-run resume path:

uv run ralphception resume
uv run ralphception resume repair
uv run ralphception terminal --approve-all --fake-session-manager

The dashboard /resume command uses the same read or repair recovery flow. Explicit historical-run targeting is still a recovery-layer capability rather than a CLI surface.

The Mental Model For Porting

If you are using Ralphception for porting, think about it as:

1. Run it in the destination repo.
2. Point it at one or more source repos elsewhere on disk.
3. Reduce source behavior into specs under .ralphception/specs/.
4. Turn approved specs into plans and execution bundles.
5. Execute child runs against the target repo.
6. Verify, merge, audit, and reopen until blocking gaps are gone.

The source repo is input, not the place where Ralphception writes its state.

Development Commands

mise run install
mise run run
mise run test
mise run typecheck

Equivalent:

uv sync
uv run ralphception
uv run pytest -v
uv run ty check src tests

What To Read In The Codebase

If you want to understand the implementation, start here:

• src/ralphception/app.py Runtime mode resolution and app bootstrap.
• src/ralphception/ui/app.py Dashboard controller and slash commands.
• src/ralphception/ui/screens/startup.py First-run bootstrap capture.
• src/ralphception/ui/screens/review.py Approval and recovery review logic.
• src/ralphception/workflow/engine.py Core run/stage/bundle orchestration.
• src/ralphception/workflow/recovery.py Resume, retry, restart, replace, lease reconciliation.
• src/ralphception/git/worktrees.py Worktree lifecycle.
• src/ralphception/git/merge.py Merge coordination.
• src/ralphception/audit/service.py Audit findings and reopen behavior.
• src/ralphception/verification/service.py Verification task construction and result persistence.

Short Version

If you want the practical answer:

• today, use uv run ralphception locally
• bootstrap the first run with the StartupBootstrapController snippet above
• inspect .ralphception/ to understand what the runtime has written
• use the dashboard slash commands for the currently wired interactive surface
• think of the project as a real core runtime that still needs a final layer of polished operator UX