Ralphy

An open-source desktop app for creating and managing content. Work with projects, media, generation tools, and local agents in one application. The Ralphy runtime and standalone CLI power the same workflows.

---

What it is

Ralphy brings content generation, project workspaces, media review, and local agents into one desktop application. This repository contains the product in apps/desktop and its runtime in cli. Desktop development previously lived in alecs5am/ralphy-desktop; its history is preserved here.

The desktop calls the runtime through its CLI and bridge contract. Agents can also use the standalone CLI for reproducible model calls, content units, renders, logs, and memory.

Run the desktop app

Requires Bun 1.4.2 or newer and macOS; development and CI pin 1.4.2. From the repository root:

bun install --frozen-lockfile
bun run install:desktop
bun run start

bun run start enters the pinned mise runtime, rebuilds the current-platform Ralphy binary, and passes its absolute path to Electron. This keeps an older global Bun or CLI from leaking into the desktop process. Install the pinned runtime once with mise install [email protected]; no per-launch environment setup is required.

bun run dev runs Electron against the Vite development server with hot reload. It uses the normal desktop profile, so saved API keys and the existing Codex/Claude Code installations and sessions remain available. Use bun run dev:renderer for the browser-only fixture mode.

bun run check:desktop   # types, tests, build, architecture and styles
bun run build:desktop
bun run package:mac     # requires the approved runtime; see apps/desktop/README.md

The desktop and runtime retain separate Bun packages and lockfiles. Install both with the commands above; no sibling checkout is needed. See the desktop guide for application details.

Demo

See what Ralphy makes → — real rendered outputs from real projects.

Cost: ~$8–12 per 30s video. Speed: ~8 min cold-start, ~25 min for a 10-batch. Engine: HyperFrames (HTML + GSAP, deterministic Puppeteer + FFmpeg render).

Install the standalone runtime

Platform	Command
macOS (Homebrew)	brew install alecs5am/tap/ralphy
Linux / macOS (curl)	curl -fsSL https://raw.githubusercontent.com/alecs5am/ralphy/main/install.sh | sh
Windows (PowerShell)	irm https://raw.githubusercontent.com/alecs5am/ralphy/main/install.ps1 | iex
Cross-platform (npm)	npm install -g @alecs5am/ralphy

All four ship the same binary.

Setup is a one-time step you run once so your agent can take over from there. These two commands are agent enablement + diagnostics, not the everyday workflow:

ralphy setup          # interactive wizard — paste the two API keys + install agent skill
ralphy doctor         # verify env is green (run this when the agent reports a problem)

Expected output:

✦ ralphy v0.3.0
▸ Dependencies          ✓ bun  ✓ ffmpeg
▸ API keys              ✓ OPENROUTER_API_KEY  ✓ ELEVENLABS_API_KEY
  ✓ ready

macOS Gatekeeper warning? You used the direct-download path. Brew / npm / install.sh bypass Gatekeeper automatically. If you hit it: xattr -d com.apple.quarantine /path/to/ralphy once and you're done.

Verify your install: every Release includes a SHA256SUMS file. shasum -a 256 -c SHA256SUMS (macOS / Linux) or Get-FileHash (Windows) confirms the binary matches.

60-second tour

In practice you say "make a spring espresso ad" in chat and the agent runs these verbs for you. Here's the surface it drives, so you can see what's happening under the hood:

# 1. Create a project
ralphy new "Spring espresso ad" --id espresso-001

# 2. Find a template by free-text utterance
ralphy template suggest "talking head rant about deadlines" -p

✦ Query: "talking head rant about deadlines"
  1. ✓ talking-head  ███████████████░  0.95  strong
  2. ✓ story-time    ███████████░░░░░  0.70  strong

# 3. Scaffold from the chosen template (sourced from the hosted library)
ralphy template use talking-head --id espresso-001

# 4. Cost-preview before spending a cent
ralphy generate image --project espresso-001 --slot scene-01-bg \
  --prompt "studio packshot, white seamless, 50mm, photoreal" --dry-run

# 5. Render the project to mp4
ralphy render espresso-001

That's it. Full CLI surface in docs/cli-surface.generated.md.

The standalone domain-store and Desktop bridge contract is documented in docs/domain-store.md. It covers explicit scope, immutable revisions, bounded content, safe DTOs, and portable Workspace transfer.

Why Ralphy

The desktop and agent runtime share these production capabilities.

	Closed SaaS (Higgsfield, HeyGen, Captions)	Other OSS (ShortGPT, MoneyPrinterTurbo)	Ralphy
Source	Closed	OSS (script-shaped)	Apache 2.0, fork-able
Who operates it	You, in their web UI	You, hand-running a script	Desktop app or your local agent
Agent surface	Their cloud agent	None	Local skills + playbooks; works in any agent
Models	Vendor lock-in	One model, hardcoded	Any OpenRouter model — Kling / Seedance / Veo / Sora / Nano-Banana
Cost transparency	Subscription black box	Free-but-you-DIY	--dry-run shows the bill before you spend
Reproducibility	Vibes	Vibes	Append-only genlogs + postmortems + templates-as-git
Quality gates	Best-effort	None	Refuse-not-warn: bad scene = no render
Reference grounding	None	None	Built-in research engine (ralphy research) + guideline library
Composer	Web canvas (theirs)	MoviePy / FFmpeg scripts	HyperFrames (HTML + GSAP) — versioned in git, tested in CI

The hard rule that makes the rest work: ralphy <verb> is the only entry-point. No ad-hoc ffmpeg shell-outs, no direct provider fetches, no orphan scripts. Every model call lands in generations.jsonl, every cost in the rollup, every failure in the postmortem.

Architecture

graph LR
    DSK[Ralphy desktop app] -->|bridge| B[ralphy runtime / CLI]
    A[Agent: Claude Code / Cursor / Codex] -->|playbooks| B
    B --> C[Provider router]
    C --> D[OpenRouter<br/>Kling / Seedance / Veo / Sora / Nano-Banana]
    C --> E[ElevenLabs<br/>TTS + Music]
    B --> F[HyperFrames composer<br/>HTML + GSAP]
    F --> G[mp4 via Puppeteer + FFmpeg]
    B --> H[Project memory<br/>genlogs · postmortems · cost rollup]
    B --> I[Hosted template library<br/>+ guidelines in git]

5 agent roles (researcher / scenarist / art-director / editor / producer) routed via AGENTS.md. The router decides which playbook the agent reads before acting.

Documentation & community

Surface	Read when
Library	Browse published units + templates with live rendered previews.
AGENTS.md	First. Routing rules + the "read the playbook before acting" discipline.
MODELS.md	Before every model call: pick from the index, then ralphy models show <id>. Claude's training is stale on model names.
docs/playbooks/	Per-role instructions (researcher, scenarist, art-director, editor, producer).
GitHub Discussions	Q&A, Show & Tell, Tester feedback.

Contributing

Use the pinned Bun 1.4.2 runtime for the commands below. See developer runtime setup for a local installation that leaves your global runtime unchanged.

git clone https://github.com/alecs5am/ralphy.git
cd ralphy && bun install --frozen-lockfile
bun run install:desktop
bun run check:desktop

bun run test                   # runtime unit + integration tests
bun run lint                   # typecheck + project lints (errors / help-examples / skills / agents-md / cli-surface)
bun run cli:surface:build      # regenerate docs/cli-surface.generated.md
bun run build:bin              # build cross-platform binaries

A pre-commit hook runs the test suite. CI runs the same on push/PR.

PRs welcome — especially:

• New model entries in MODELS.md (index row) and docs/models/<kind>.md (detail) with real cost numbers + known pitfalls.
• Bug fixes in cli/lib/providers/.
• New guidelines under guidelines/<slug>/ (image-prompt rules — tag-able from chat as @guideline:<slug>).

For non-trivial changes, open an issue first or start a discussion.

License

Apache 2.0. Use, fork, ship to prod — patent grant included.

---

Built with Claude Code, Bun, HyperFrames, OpenRouter, and ElevenLabs.