ralphception 0.2.0

Codex-native orchestration runtime.

Ralphception

ralphception is a Codex-shaped orchestrator for long-running Ralph-loop work:

• one durable task/session per target repo
• Socratic intake that turns a starting prompt into durable artifacts
• explicit PRD, plan, loop-plan, and todo artifacts before execution
• child runs in worktrees for loop execution, verification, merge, and audit
• reopen and continue until the task is explicitly complete or explicitly blocked

The runtime is durable and repo-local. The product surface is now simple:

• uv run ralphception launches the inline interactive shell
• uv run ralphception exec "..." runs non-interactively
• uv run ralphception e "..." is the short alias

Quick Start

mise run install
mise run run

Equivalent uv commands:

uv sync
uv run ralphception
uv run ralphception exec "port parser"

Once the package is published, the intended entry points are:

uvx ralphception
uvx ralphception exec "port parser"

Interactive Shell

uv run ralphception opens the default inline shell in the current repo.

The primary transcript lives in normal terminal scrollback, not inside a boxed full-screen viewport. Ralphception writes durable milestones and loop progress directly into the terminal so you can rely on normal scrollback while work runs.

The default lifecycle is artifact-first:

1. Socratic intake
2. durable intake summary / PRD / plan / todos
3. explicit Ralph-loop planning
4. loop execution in child worktrees
5. consolidation, merge, audit, and reopen if needed

The shell drives the same durable runtime used everywhere else. User replies, blockers, loop progress, and settled outcomes all write into the same .ralphception/ workspace state.

Non-Interactive Exec

uv run ralphception exec "..." runs the task loop without opening Textual.

Example:

uv run ralphception exec \
  "port parser" \
  --source-repo /path/to/source-repo

Useful flags:

• --repo-root <path> to operate on another workspace
• --source-repo <path> to attach one or more source repos
• --approve-all / --no-approve-all to control automatic approval of spec and execution-bundle gates
• --fake-session-manager to inject the deterministic fake backend used by the test suite

exec defaults to --approve-all because it is the non-interactive path. If you want to stop at reviews, use --no-approve-all and switch back to the chat shell.

Prompt input can also come from stdin:

printf '%s\n' "port parser" | uv run ralphception exec -

Live execution requires the codex CLI backend on your PATH. If you are only verifying the local runtime loop, use --fake-session-manager.

Runtime Flow

The durable task loop is:

flowchart TD
    A["Initial prompt + optional source repos"] --> B["Socratic intake"]
    B --> C["Write intake summary / PRD / plan / todos"]
    C --> D["Build explicit plan graph and loop graph"]
    D --> E["Execute one or more Ralph loops in child worktrees"]
    E --> F["Verification + merge"]
    F --> G["Audit + consolidation"]
    G --> H{"Blocked or more loops needed?"}
    H -- yes --> D
    H -- no --> I["Done"]

Runtime State

Ralphception writes disposable runtime state under .ralphception/:

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

Important early files:

• .ralphception/runs/run-root/startup.json The captured seed prompt and source repos.
• .ralphception/runs/run-root/intake.md The intake artifact derived from startup.
• .ralphception/specs/mission-spec.md The current root spec artifact.
• .ralphception/plans/mission-plan.md The current root plan artifact.
• .ralphception/events/run-root.jsonl The root event log.

The directory is intentionally disposable and should not be committed.

Continuity

Repo-local task state is backed by XDG lease state:

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

The recovery layer can:

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

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

Codebase Map

If you want to understand the implementation, start here:

• src/ralphception/app.py Product entry points for the inline shell and exec mode.
• src/ralphception/cli.py Public CLI surface.
• src/ralphception/runtime/inline_shell.py Default scrollback-first interactive shell.
• src/ralphception/runtime/supervisor.py Shared runtime mode resolution and artifact-first orchestration entry points.
• src/ralphception/runtime/bootstrap.py Durable startup capture and intake artifact creation.
• src/ralphception/headless.py Long-running headless orchestrator.
• src/ralphception/workflow/engine.py Core run, stage, and bundle orchestration.
• src/ralphception/workflow/recovery.py Lease reconciliation and resume operations.
• src/ralphception/git/worktrees.py Worktree lifecycle.
• src/ralphception/git/merge.py Merge coordination.
• src/ralphception/audit/service.py Audit findings and reopen behavior.

Mental Model For Porting

When using Ralphception for a port:

1. run it in the destination repo
2. point it at one or more source repos on disk
3. reduce source behavior into approved specs
4. turn approved specs into plans and execution bundles
5. execute child runs against the destination repo
6. verify, merge, audit, and reopen until blocking gaps are gone

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