# Vibeframe > AI-Native Video Editor — CLI-first, MCP-ready. Generate, edit, and ship videos from your terminal. - **Type:** MCP server - **Install:** `agentstack add mcp-vericontext-vibeframe` - **Verified:** Pending review - **Seller:** [vericontext](https://agentstack.voostack.com/s/vericontext) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [vericontext](https://github.com/vericontext) - **Source:** https://github.com/vericontext/vibeframe - **Website:** https://vibeframe.ai ## Install ```sh agentstack add mcp-vericontext-vibeframe ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # VibeFrame Turn a written brief into a rendered MP4 using a coding agent. VibeFrame is a CLI tool and MCP server for agentic video workflows. It takes a brief, scaffolds a structured storyboard project, routes generation calls to AI providers, and produces a reviewed MP4. The CLI is the stable runtime — JSON output, dry runs, cost gates, and machine-readable reports that Codex, Claude Code, Cursor, and other host agents can act on. Your existing coding agent is the outer loop. VibeFrame provides the video-specific commands and reports. `vibe agent` exists as a fallback when you do not have another agent available. [](LICENSE) [](https://github.com/vericontext/vibeframe/actions/workflows/ci.yml) [](https://github.com/vericontext/vibeframe/stargazers) ## Directed AI video — one character, many scenes The four scenes below are the **same character**, directed across a short film from one brief — **character sheet → image storyboard (one keyframe still per scene) → Seedance image-to-video → composed render**. Open source, MIT. ▶ **[Watch the full render](https://github.com/vericontext/vibeframe/releases/download/v0.113.4/vibeframe-showcase.mp4)** (1080p, generated end-to-end by `vibe build`). How it works (run it today): ```bash # 1. one character sheet, reused everywhere (frontmatter: characters: { nova: "..." }) # 2. per beat: a keyframe still (image storyboard) + the motion prompt # keyframe: "NOVA on the starting grid, low-angle hero shot, golden light" # video: "slow push-in as she looks up" # 3. review the image storyboard cheaply, then animate only what you approve: vibe build my-film --skip-video # generate the keyframe stills (cheap), review them vibe build my-film --max-cost 12 # animate the approved stills (Seedance image-to-video) ``` Prompt craft for both models is in the [AI video prompting playbook](docs/ai-video-prompting.md); the storyboard cues (`characters:`, `keyframe:`) are documented in [docs/projects.md](docs/projects.md). ## Requirements - Node.js 20+ - FFmpeg - Chrome or Chromium (for HTML scene rendering) - API keys only for the providers you use (BYO-key) Free/local paths are available for many editing tasks and for Kokoro TTS. AI image and video generation requires provider keys such as `OPENAI_API_KEY`, `FAL_API_KEY`, `GOOGLE_API_KEY`, and others listed in [MODELS.md](MODELS.md). ## Install ```bash curl -fsSL https://vibeframe.ai/install.sh | bash vibe doctor ``` The installer places the CLI under the XDG data directory (`~/.local/share/vibeframe` by default). User-scope API keys live in `~/.vibeframe/config.yaml`; project-scope setup writes `./.vibeframe/config.yaml`. When a project config exists at or above your current directory, VibeFrame uses that project config in isolation and does not merge user-scope keys. > **npm package names:** the CLI is published as > [`@vibeframe/cli`](https://www.npmjs.com/package/@vibeframe/cli) (binary > `vibe`) and the MCP server as > [`@vibeframe/mcp-server`](https://www.npmjs.com/package/@vibeframe/mcp-server). > There is no bare `vibeframe` npm package from this project — that name belongs > to an unrelated package, so `npx vibeframe` will not run this tool. For local development: ```bash git clone https://github.com/vericontext/vibeframe.git cd vibeframe pnpm install pnpm build pnpm vibe --help ``` ## How The Pieces Fit Together VibeFrame has two main flows: - **Project flow:** scaffold a storyboard, let an agent revise it, build assets, render, and inspect. This is the primary path. - **One-shot flow:** edit or transform existing media directly with `generate`, `edit`, `remix`, `audio`, or a YAML pipeline. No storyboard needed. The architecture is: ```text CLI (Commander.js + Agent) -> Engine (Project state) -> Core (Zustand + FFmpeg) -> AI Providers ``` Within a project, the files have defined roles: | Path | Role | | --------------- | --------------------------------------------------------------------------------- | | `brief.md` | Optional rough input before `vibe init`; can be messy notes, links, or one line. | | `STORYBOARD.md` | Beats, narration, duration, and image/video/music cues. The intent layer. | | `DESIGN.md` | Palette, typography, layout, motion, and transitions. The visual system. | | `media/` | User-provided source files: photos, screenshots, logos, B-roll, voice recordings. | | `assets/` | Generated or canonical build artifacts: narration, backdrops, music, video clips. | | `renders/` | Final and intermediate MP4 outputs. | | `references/` | Composition rule docs installed by VibeFrame skills; not for user media. | `vibe.config.json` owns the project contract (provider, model, quality, and build defaults). The composition engine today is Hyperframes (HTML/CSS/JS scene rendering in a headless browser). ## Quick Start ```bash vibe setup vibe doctor vibe guide ``` Scaffold a project from a brief: ```bash mkdir -p launch/media # optional: add your own photos, logos, screenshots, or B-roll # cp ~/Desktop/product-shot.png launch/media/ cat > brief.md vibe init launch --from brief.md --json -> edit launch/STORYBOARD.md and launch/DESIGN.md -> vibe plan launch --json -> vibe build launch --dry-run --max-cost 5 --json -> vibe build launch --max-cost 5 --json -> vibe status project launch --refresh --json -> vibe inspect project launch --json -> vibe render launch --json -> vibe inspect render launch --cheap --json "fix quality issues from the render review" -> read review-report.json -> vibe scene repair launch --json -> edit STORYBOARD.md or composition artifacts only where needed -> vibe render launch --json -> vibe inspect render launch --cheap --json ``` `inspect` returns a `review-report.json` with pre-classified `nextActions`: run `safeToAutoRun:true` actions automatically, ask before `requiresConfirmation:true` actions, and use `retryWith` only as a fallback. `fixOwner:"vibe"` means the CLI can repair it deterministically; `fixOwner:"host-agent"` means the outer loop (or a human) must edit `STORYBOARD.md`, `DESIGN.md`, or compositions. ### Goal mode prompts For Codex: ```text /goal Build launch/ into a reviewed VibeFrame MP4 from brief.md. Use vibe context/schema first when command details are unclear. Use --json for all vibe commands. Run --dry-run before paid operations and keep generated-asset spend under $5 with --max-cost 5 where supported. Read build-report.json and review-report.json before choosing the next action. Prefer nextActions: run only safeToAutoRun:true actions automatically, ask before requiresConfirmation:true actions, and use retryWith only as the compatibility fallback. Treat fixOwner:"vibe" issues as deterministic CLI repair work and fixOwner:"host-agent" issues as storyboard, DESIGN.md, or composition edits. Stop only when launch/renders/final.mp4 exists, the target duration is 30s or less, the aspect ratio is 16:9 unless brief.md says otherwise, vibe inspect render launch --cheap --json reports no errors, any AI review score is at least 90 when AI review is requested, and every remaining host-agent issue is fixed, intentionally accepted with a written reason, or reported as blocked. ``` For Claude Code: ```text /goal Create the final VibeFrame project render for launch/ using the native Claude Code goal loop as the outer loop. Use vibe commands with --json, run dry-run before paid operations, cap build spend at $5 with --max-cost 5, and use build-report.json plus review-report.json as the loop state. Follow nextActions first, run only safeToAutoRun:true actions automatically, ask before requiresConfirmation:true actions, and use retryWith only as a fallback. Distinguish fixOwner:"vibe" from fixOwner:"host-agent" when deciding whether to run vibe scene repair or edit STORYBOARD.md, DESIGN.md, or compositions. Stop only when launch/renders/final.mp4 exists, duration is within the requested 30s target, aspect ratio is 16:9 unless the brief overrides it, render inspection status has no errors, any AI review score is >= 90 when AI review is requested, and unresolved host-agent issues are either fixed, explicitly accepted with rationale, or reported as blocked. ``` ### Configuring hosts `vibe init` creates agent guidance files for Codex, Claude Code, Cursor, Aider, Gemini CLI, OpenCode, and a universal `AGENTS.md` fallback. `vibe host` turns that guidance into app-ready configuration: ```bash vibe host list --json vibe host setup all # print snippets only vibe host setup cursor --write # write .cursor/mcp.json vibe host doctor all --json ``` By default, `--write` is required to apply config; `vibe host setup` prints only. For Claude Desktop, pass the workspace directory so relative project names resolve correctly: ```bash vibe host setup claude-desktop ~/dev/videos --write ``` ### Schema and introspection ```bash vibe schema --list # full command catalog vibe schema --list --surface public # first-run / product surface only vibe schema --list --filter free # narrow to cost tier vibe schema --json # JSON Schema for one command vibe context # agent quickstart: rules, envelope, conventions vibe guide # workflow guides vibe guide motion vibe guide scene vibe guide pipeline ``` `vibe schema` is the source of truth for command availability and parameters. The `surface` field on each entry signals intent: `public` = first-run product path; `agent` = host-agent automation; `advanced`/`legacy` = compatible power primitives. ## MCP Server The CLI is the primary runtime. For hosts that prefer MCP, VibeFrame also ships `@vibeframe/mcp-server` (binary `vibeframe-mcp`). **Claude Desktop users:** install the prebuilt extension instead of editing JSON — download [vibeframe.mcpb](https://github.com/vericontext/vibeframe/releases/latest/download/vibeframe.mcpb) and drop it into **Settings → Extensions**, then pick a workspace folder. For other hosts, generate snippets with: ```bash vibe host setup codex vibe host setup claude vibe host setup cursor ``` Or configure directly: ```json { "mcpServers": { "vibeframe": { "command": "npx", "args": ["-y", "@vibeframe/mcp-server"] } } } ``` See [packages/mcp-server/README.md](packages/mcp-server/README.md) for tool, resource, and prompt details. ## Providers VibeFrame routes to multiple providers for LLMs, image generation, video generation, TTS, transcription, and analysis. Common environment variables: ```text OPENAI_API_KEY ANTHROPIC_API_KEY GOOGLE_API_KEY FAL_API_KEY ELEVENLABS_API_KEY RUNWAY_API_SECRET KLING_API_KEY XAI_API_KEY REPLICATE_API_TOKEN OPENROUTER_API_KEY IMGBB_API_KEY ``` The canonical list is `vibe doctor --json | jq '.data.providers'`, which stays in sync with new providers automatically. ```bash vibe setup --show # list configured keys vibe doctor # verify keys and dependencies ``` For model and provider details, see [MODELS.md](MODELS.md). Cost tiers are stamped on commands. General expectations: - **Free/local:** schema, setup/doctor, timeline/batch/detect/media, many FFmpeg edits - **Low:** speech, transcription, inspection, simple AI-assisted edits - **High:** image generation, storyboard/motion generation - **Very high:** video generation and expensive provider-backed transforms Use `vibe schema --list --filter ` to check before running. ## Relationship To Composition Engines VibeFrame wraps lower-level composition engines rather than replacing them: | Layer | Owns | | -------------------------------------------------------- | ------------------------------------------------------------------------------- | | [Remotion](https://github.com/remotion-dev/remotion) | React-based programmatic video and component-driven motion graphics. | | [Hyperframes](https://github.com/heygen-com/hyperframes) | HTML/CSS/JS scene composition and deterministic browser capture. | | VibeFrame | Storyboard/design files, provider routing, build reports, render inspection, edit/remix commands, and host-agent guidance. | Use Hyperframes directly when the job is only HTML scene authoring and rendering. Use VibeFrame when the job includes storyboard planning, image/video/audio generation, narration, build reports, or editing steps around the composition layer. VibeFrame is not affiliated with HeyGen. See [CREDITS.md](CREDITS.md) for dependency and provenance notes. ## Repository Layout ```text packages/cli/ CLI and agent mode packages/core/ Timeline engine and shared core types packages/ai-providers/ Provider registry and implementations packages/mcp-server/ MCP server package packages/ui/ Shared React UI apps/web/ Next.js landing/demo app docs/ Compact public docs scripts/ Install, docs generation, demos, and maintainer helpers tests/ Manual smoke checks outside CI ``` ## Development ```bash pnpm install pnpm build pnpm test pnpm lint ``` Useful local commands: ```bash pnpm vibe --help pnpm -F @vibeframe/cli test pnpm -F @vibeframe/web dev ``` ## Contributing Contributions are welcome: bug fixes, provider integrations, CLI UX improvements, docs, and tests. ```bash pnpm scaffold:provider pnpm scaffold:command ``` See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide. ## Reference - [MODELS.md](MODELS.md): provider and model reference. - [CHANGELOG.md](CHANGELOG.md): versioned release notes. - [FUNCTIONS.md](FUNCTIONS.md): workflow lanes, command routing, and agent usage rules. - [ROADMAP.md](ROADMAP.md): short public roadmap. - [docs/projects.md](docs/projects.md): project file roles, profiles, characters, and dry runs. ## License MIT. See [LICENSE](LICENSE). ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [vericontext](https://github.com/vericontext) - **Source:** [vericontext/vibeframe](https://github.com/vericontext/vibeframe) - **License:** MIT - **Homepage:** https://vibeframe.ai Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-vericontext-vibeframe - Seller: https://agentstack.voostack.com/s/vericontext - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.