RAE is a local-first toolkit for controlled repository changes. It combines versioned graph workflows, isolated Git worktrees, schema-validated artifacts, human checkpoints, verification gates, and durable local run evidence.

The repository distributes source only: there is no published package, supported container, deployed service, or stable API. The hosted control-plane code and workflow 2.2 are experimental.

What RAE provides

• a graph-native workflow engine with bounded concurrency, joins, checkpoints, repair loops, and immutable attempt envelopes
• autonomous repository work in isolated Git worktrees, with Codex as the default provider and explicit macOS-only OpenCode routes
• a bearer-authenticated operator console bound to loopback
• optional local repository, run, and temporal-memory graph projections
• the independent Ralph audit, linting, and transactional fixing loop
• deterministic quality, review, trace, profile-installation, and repository hygiene tools
• an experimental PostgreSQL control plane, remote worker, object-store boundary, and HTTP MCP endpoint

RAE does not commit, push, publish, deploy, or activate workflow revisions on a user's behalf. The custom command provider is an unsandboxed test integration, not an operational backend. OpenCode writes require an isolated RAE worktree and the supported macOS Seatbelt boundary.

Screenshot tour

These are deterministic CLI captures and sanitized operator fixtures, not evidence from a live run.

The command surface prints the supported entry points and their arguments:

Autonomous runs default to checkpoints before mutation and release, and the agent help surface shows the sandbox and provider boundaries:

The loopback operator renders run state, gates, evidence references, and human checkpoints. Its workflow editor authors revision-controlled workflows with synchronized Loop, Graph, Analyze, and JSON views, a pinned active revision and digest, and an inspector for budgets, loop bounds, and gate flags.

The same editor reflows for narrow windows:

Try the static Pages demo to click through the interface against an in-browser mock. It has no repository or backend access. The full operator stays bearer-authenticated and loopback-only.

Requirements

• Node.js 24 or newer, npm and Git
• CMake and a C compiler for the native filesystem bridge
• the Codex CLI for provider-backed autonomous runs or Ralph
• the OpenCode CLI for explicitly selected OpenCode routes on macOS

Prepare a source checkout

Run from the repository root:

npm ci --ignore-scripts
npm run build
npm run rae -- doctor

The build compiles strict TypeScript and the descriptor-relative filesystem bridge. macOS requires the Xcode command-line tools; Linux requires CMake, Make and a C compiler. Runtime commands execute compiled JavaScript.

The experimental platform has a separate lockfile and is outside the root npm workspace. Install and build it when that package or the complete gate is in scope:

npm ci --prefix apps/platform --ignore-scripts
npm --prefix apps/platform run build

Quick start

Inspect the supported command families:

npm run rae -- --help
npm run rae -- agent doctor

Run a task against a committed target repository in an isolated worktree:

npm run rae -- agent run \
  --project-root /path/to/target-repository \
  --task "Add a tested health endpoint and document its behavior"

The command prints the worktree, run ID, and .pipeline/runs/<run-id>/run-report.md. Use --through plan to stop before a writer node. New isolated runs use a pipeline/<run-id> branch and place the worktree under the target repository's Git metadata at .git/rae-worktrees/<run-id>.

Serve the local operator for explicitly allowed repositories:

npm run rae -- operator serve --project /canonical/path/to/repository

Run Ralph after creating its package-local prd.json:

npm run rae -- ralph --check
npm run rae -- ralph --mode audit 10

See the engine guide, operator guide, and Ralph guide for their complete interfaces.

Repository map

Path	Purpose and boundary	Documentation
packages/engine/	Private npm workspace package; workflow, run, provider, graph, and evidence runtime	Engine
packages/contracts/	Private workspace package exporting immutable versioned schemas	Contracts
apps/operator/	Private workspace application; loopback console and static mock demo	Operator
apps/platform/	Separately installed experimental control plane and worker	Platform
packages/ralph/	Independent TypeScript story loop	Ralph
packages/dev-tools/	Independently invoked TypeScript quality, review, and trace tools	Quality gate, review, trace
workflows/	Repository-owned workflow definitions and recipes	Graph tutorial
integrations/agent-adapters/	Adapter manifest, templates, generator, and derived runner guidance	Adapter generation
profiles/agent-environments/	Sanitized profile templates and transactional installers	Profiles
tools/repo-hygiene/	Narrow repository-maintenance utilities	History cleaner
scripts/	Umbrella CLI and repository-wide validation	CLI reference

The architecture guide describes dependency direction, runtime flows, state ownership, and security boundaries. The documentation guide routes readers into tutorials, how-to guides, references, explanations, and governance.

Configuration

Configuration is owned by the runtime that consumes it:

Surface	Configuration entry point
Autonomous engine	CLI flags, packages/engine/policies/, workflow JSON, and optional execution profiles
Workflow registry and graph memory	Owner-controlled state under the target Git common directory
Operator	--project, repeatable --execution-profile, or remote-operator options
Ralph	prd.json, command flags, and documented RALPH_* variables
Experimental platform	RAE_PLATFORM_CONFIG TOML and worker environment variables
Public profiles	Sanitized templates under profiles/agent-environments/

Do not put credentials or unrelated private material in tasks, policy files, profiles, artifacts, reports, or committed examples. Provider-backed commands transmit selected task and context data to the configured provider.

Development and verification

Read CONTRIBUTING.md before changing behavior. The prepared-checkout verification command is:

npm run verify -- --skip-install

The command builds the source, checks maintained TypeScript and documentation, and exercises the runtime entry points. npm run build covers root workspaces; build the platform separately.

For a complete verification run:

npm run verify -- --release-candidate

Support, security, and license

Use SUPPORT.md for usage questions and SECURITY.md for private vulnerability reporting and trust boundaries. RAE is licensed under the MIT License.