Rafiki

Rafiki is a local-first workflow for AI image generation, batch prompt runs, reviewing outputs in a browser, and rendering HTML to PNG.

It combines:

• a Node CLI entry point: rafiki and the legacy alias image-gen
• a Python generation engine for Gemini and OpenAI image models
• a local review portal for comparing runs, rating outputs, and browsing a project library
• a Puppeteer-based HTML-to-image renderer for cards, diagrams, and slide art

Rafiki is designed to run from a checkout on your machine. Your API keys stay local. There is no hosted Rafiki service.

Status

Rafiki is ready for real work. The recommended install path is: clone the repo, install dependencies, run locally. Roadmap: docs/ROADMAP.md. The current public use-case focus is the keynote visual workflow: turning talk notes into prompt packs, reviewable image candidates, slide assets, and downstream web or social artifacts.

What Rafiki Does

• Generate single images from a prompt
• Run batches from Markdown prompt files
• Keep every batch in an isolated run-* directory
• Rebuild viewers without re-running generation
• Review outputs in a local comparison viewer and library
• Rate images as starred, rejected, or unreviewed
• Render HTML files to PNG with Puppeteer
• Register image outputs from other directories on disk
• Export approved assets for downstream workflows

Quickstart

1. Clone and install

Rafiki requires Node.js 20.17+ with npm 10+ and Python 3.11+.

git clone https://github.com/WalksWithASwagger/rafiki.git
cd rafiki

npm install

python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt
./.venv/bin/pip install -r requirements-dev.txt

2. Add provider keys

cp .env.example .env

Add at least one of:

• GOOGLE_API_KEY for Gemini models
• OPENAI_API_KEY for OpenAI image models

3. Run setup diagnostics

npm run doctor

Or:

npx rafiki --doctor

4. Generate something

npx rafiki --prompt "A cinematic portrait of a radio host in a neon-lit studio" \
  --output output.png

For a public batch fixture:

npx rafiki examples/quickstart-image-prompts.md --dry-run --no-viewer

For the keynote visual workflow fixture:

npx rafiki examples/keynote-visual-workflow-prompt-pack.md --dry-run --no-viewer

Common Workflows

Single prompt

npx rafiki --prompt "A creative strategist sketching a systems map" --output hero.png

Batch prompt file

npx rafiki /path/to/image-prompts.md --output-dir /path/to/output/project

Styled generation

npx rafiki /path/to/image-prompts.md \
  --style hopecode \
  --output-dir /path/to/output/project

No style suffix

npx rafiki --prompt "Minimal monochrome diagram" --no-style --output diagram.png

Reference images

npx rafiki \
  --prompt "Keep the composition, modernize the visual language" \
  --reference-image /path/to/reference.png \
  --output output.png

HTML to PNG

npx rafiki --render /path/to/card.html
npx rafiki --render-dir /path/to/html-assets/

Python directly

./.venv/bin/python generate.py --prompt "Your prompt" --output image.png
./.venv/bin/python generate.py --prompt-file image-prompts.md --output-dir ./images/

MCP

Rafiki can be installed as a local MCP server so Codex, Claude Code, and other MCP clients can call it as tools instead of shelling out manually.

codex mcp add rafiki -- /path/to/rafiki/.venv/bin/python /path/to/rafiki/mcp_server.py
claude mcp add --scope user rafiki -- /path/to/rafiki/.venv/bin/python /path/to/rafiki/mcp_server.py

Exposed tools include rafiki_generate, rafiki_batch, rafiki_list_styles, rafiki_usage, rafiki_status, and rafiki_run for the broader generate.py CLI surface.

Details: docs/MCP.md

Local Portal

Start the live portal shell:

python3 generate.py serve

By default it runs on http://localhost:7433/. Open http://localhost:7433/library to use the current TypeScript image library or http://localhost:7433/generate to build dry-run-first image generation runs.

The portal adds:

• persistent ratings stored on disk
• cross-project browsing and search
• viewer pages for image triage and metadata review
• run pages with missing-image placeholders and direct viewer links
• export, registry, health, and spend routes backed by local APIs
• generate workspace for single prompts, inline batches, Markdown prompt packs, model/style choices, and library/media references

The Generate route writes into output/<project>/run-* through the same generation path as the CLI, so portal-generated runs show up in the normal viewer and library flow. It defaults to dry-run; real provider calls require explicit confirmation in the UI. Python remains the local filesystem, provider, and API authority; the frontend is spawned behind the Python server. The legacy rollback surfaces are available at /legacy-suite and /legacy-library.

The TypeScript portal is currently a repo-checkout capability. The public npm package intentionally excludes frontend/, so npx rafiki serve from a package install falls back to the legacy portal routes instead of building or starting the React shell. See Frontend Shell for the package boundary and release-policy checkpoint.

Useful commands:

python generate.py view <project>
python generate.py view <project> --all-runs
npx rafiki view <project> --all-runs
python generate.py library
python generate.py library --open
python generate.py archive-health --cleanup-report
npm run smoke:dry-run

library builds the full local archive: every run-* image under output/ and any configured extra-output roots, with approval state overlaid from approved/index.json when available.

Prompt File Format

Rafiki batch runs parse numbered Markdown sections with blockquote prompts:

## 1. Hero Image
**For:** Article header
**Prompt:**
> A documentary-style portrait of a community organizer...

## 2. Quote Card
**For:** Social media
**Prompt:**
> Bold editorial typography over textured paper grain...

Per-prompt overrides are supported:

## 1. Hero Banner
**Aspect Ratio:** 16:9
**Model:** gpt-image-2
**Style:** kk
**Quality:** high
**Prompt:**
> ...

Models

Rafiki supports both Gemini and OpenAI image models through the same CLI.

• gemini-2.5-flash-image: fast iteration
• gemini-3-pro-image-preview: higher-end Gemini image generation
• gpt-image-2: strong general-purpose OpenAI image generation
• gpt-image-1
• dall-e-3

The CLI, portal, and MCP default is gemini-2.5-flash-image. Pass --model to select another provider or model explicitly. Choose Gemini for fast local iteration and Gemini Pro reference or high-resolution work. Choose OpenAI when the prompt set was authored against OpenAI outputs, when you need OpenAI-only model behavior, or when using the separate gpt-image-1 Streamlit workflow.

Details: docs/MODEL-POLICY.md

Prompt And Media Boundary

The GitHub repository is public, so any tracked prompt, asset, or doc should be treated as public. Keep private prompt libraries, private reference media, generated review outputs, and local-only paths outside the repo or untracked.

The public npm package stays narrower by design. It ships runtime code, docs, styles, config examples, and only explicitly listed example prompt packs such as examples/quickstart-image-prompts.md and examples/keynote-visual-workflow-prompt-pack.md. It does not ship the frontend/ workspace or frontend build artifacts until a maintainer approves a package-policy change.

Details: docs/PROMPT-MEDIA-POLICY.md

Styles

Built-in styles are configured in styles/styles.yaml and can be composed with +.

Examples (not exhaustive):

• kk
• hopecode
• bcai
• futureproof-mythic
• bcai-ecosystem
• upgrade
• zine
• gni
• femme
• indigenomics
• cmvan

Useful commands:

npx rafiki --list-styles
npx rafiki --prompt "..." --style kk+bcai

External Project Registry

If you want the portal and library to include outputs that live outside this repo, copy the example file and create a local override:

cp config/extra-outputs.json.example config/extra-outputs.local.json

Example:

{
  "workshop-deck": "/absolute/path/to/another/project/output",
  "campaign-assets": "/absolute/path/to/a/generated-images-directory"
}

This file is intentionally gitignored.

For file:// viewing without the server, create symlinks into output/:

python generate.py link-projects

Security and Scope

• Provider keys belong in your shell environment or an untracked .env
• python generate.py serve binds to 127.0.0.1 by default
• --public refuses to start unless both PORTAL_USERNAME and PORTAL_PASSWORD are set
• Rafiki is a local-first tool, not a hosted multi-user platform

Read:

• SECURITY.md
• docs/SCOPE.md

Development

Useful commands:

npm test
npm run public:check
npm run pack:check
npm run docs:check
python3 -m pytest -q

Contribution guide: CONTRIBUTING.md

Docs

Start with the docs index for the full map.

Key references:

• Scope
• MCP
• Command Center
• Asset Registry
• Deployment
• Delivery Pipeline
• Scheduled Regeneration

License

MIT. See LICENSE.