faelo

Faelo for Claude Code

Make polished, multi-variant video ads without leaving your terminal. This plugin turns Claude Code into the orchestrator of the Faelo pipeline: you describe a brief (a URL, a paragraph, a voice note, a screenshot) and Claude drives the whole flow — ingest → plan → script → storyboard → render → assemble → export — calling the remote Faelo engine over a key-gated MCP connection.

No web UI. No dashboards. Just a conversation that ends in finished ads.

---

Install (≈1 minute)

Requires a recent Claude Code (run claude --version; if /plugin is missing, update) and a personal Faelo API key (format fae-<label>-<hex>). Ask the Faelo team for one.

This plugin is distributed as its own repository (johnnybq/faelo-plugin) whose root is the marketplace — /plugin marketplace add reads .claude-plugin/marketplace.json from a repo root, so it cannot point inside the monorepo (and you don't want friends cloning the whole private codebase anyway).

/plugin marketplace add johnnybq/faelo-plugin     # the dedicated, public plugin repo
/plugin install faelo

On install you'll be prompted for your Faelo API Key — paste your fae-… key. It's stored encrypted in your system keychain (never in a file, never in git). There is no /plugin config command — to change the key later, run /plugin, disable then re-enable faelo to be re-prompted. After entering the key, start a new Claude Code session so the MCP connection picks it up.

Try it before publishing the repo: claude --plugin-dir /path/to/faelo-plugin/plugins/faelo loads the plugin directly for the current session (you'll still be prompted for the key).

Verify:

/faelo:whoami

You should see your account label, credit balance, and project count.

Don't have a key? They're issued per-person by the Faelo team. Ping them.

---

Use it

/faelo:new https://your-product.com           # start an ad, iterate the storyboard
/faelo:ship a 30s reel for my coffee brand     # one-shot, autonomous, single budget OK
/faelo:status                                  # account + where the current ad is
/faelo:render                                  # gate cost, render the committed storyboard
/faelo:doctor                                  # something's off? diagnose it

Or just talk: "make me a 9:16 ad for this landing page, cinematic, ~30s." Claude picks the right skill.

How spend works: reference images cost cents and you iterate freely; the video render is the cost cliff (~$6-8 for a full ad). Claude always shows the estimate and you approve the render via Claude Code's permission prompt — nothing is spent silently. A budget_cap_usd on the project is your hard ceiling for autonomous runs.

---

How it works

Claude Code  ──HTTPS + Bearer key──▶  Faelo MCP server (FastMCP, key-auth)  ──▶  pipeline
  (you, the                                │  every key → an isolated account
   orchestrator)                           │  (your own projects / credits / costs)
   • whoami / create_project               ▼
   • ingest / plan / script              FAL · Veo · ElevenLabs · Nano Banana 2 · …
   • storyboard refs (cheap, iterate)
   • render video (gated) → assemble → export

Your key maps 1:1 to a sandboxed Faelo account — you only ever see your own work.

---

For Faelo operators (running the engine locally)

If you have the Faelo repo checked out (with .venv, the DB tunnel up, and provider keys in .env.local), you can drive the SAME tools over a local stdio server instead of the remote one — no key needed (falls back to a dev account):

1. Copy the local template to the repo root: cp faelo-plugin/.mcp.local.json .mcp.json
2. Start a Claude Code session in the repo. The faelo MCP server runs reelforge-mcp over stdio against reelforge_dev.
3. Add REELFORGE_MOCK_PROVIDERS=1 to the server env (already in the template) to run the whole pipeline at $0 while testing.

The deterministic one-shot engine is python3 scripts/ship_ad.py config/<ad>.json (--dry-run for a free cost estimate). Remote plugin users don't have this — for them the autonomous MCP flow (/faelo:ship) is the one-shot.

---

What's inside

• skills/ — faelo-orchestrate (storyboard-first playbook), faelo-ship (autonomous one-shot), faelo-doctor (connectivity preflight).
• commands/ — /faelo:new, /faelo:ship, /faelo:status, /faelo:render, /faelo:whoami, /faelo:doctor.
• hooks/ — a cost-guard advisory before any paid render step.
• .mcp.json — the remote, key-gated MCP connection.

Publishing (for the Faelo team)