vibeframe
AGENTS.md185 starsChanged todayMITView on GitHub
VibeFrame is a frontier-video-generation layer for coding agents: CLI-first, MCP-ready. It generates video assets on the user's own provider keys (Seedance, Runway, Kling, Gemini Omni) behind dry runs and a hard --max-cost ceiling, delegates scene composition to upstream Hyperframes, and builds the generation, cost, and review layer around it. Monorepo: Turborepo + pnpm workspaces. ESM. TypeScript strict mode. Architecture: Use vibe schema --list and vibe schema <command> as the source of truth for CLI command availability and parameters. Canonical user-facing…
- Reads credentials
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository11 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- releaseSkill
- sync-checkSkill
- testSkill
- vibe-pipelineSkill
- vibe-sceneSkill
- releaseSkill
- sync-checkSkill
- testSkill
- vibe-pipelineSkill
- vibe-sceneSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
24 rules. About 0 are common, 6 are distinctive, and 18 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
18
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 36
Use vibe schema --list and vibe schema <command> as the source of truth for CLI command availability and parameters.
- Very specific: line 52
Do not introduce docs, examples, or agent instructions that use removed namespaces such as vibe ai, vibe project, vibe export, vibe …
- Very specific: line 58
When invoking VibeFrame commands from an agent context:
- Distinctive: line 60
Treat your host's agent loop (Claude Code, Codex, Cursor, or another coding-agent host) as the outer loop for long-running video work.
- Very specific: line 65
Prefer --json for structured output.
- Very specific: line 66
Run --dry-run before paid or mutating operations when the command supports it.
- Very specific: line 67
When a review report includes nextActions, prefer it over inventing commands: run only safeToAutoRun:true actions automatically, ask before …
- Very specific: line 71
Use vibe schema <command> before constructing non-trivial arguments.
- Very specific: line 74
Use --stdin for complex option payloads instead of fragile shell quoting.
- Distinctive: line 82
When adding CLI commands, expose them as MCP tools only when natural-language invocation is useful.
- Very specific: line 91
Add a manifest entry (packages/cli/src/tools/manifest/) with a schema that matches the CLI behavior.
- Distinctive: line 92
Add focused tests for the executor and wrapper.
- Distinctive: line 96
Do not maintain a separate hardcoded cost table in docs or prompts.
- Very specific: line 114
Run pnpm build after TypeScript changes.
- Very specific: line 115
Run pnpm lint after changes and fix errors before committing.
- Distinctive: line 116
Do not leave unused imports.
- Very specific: line 117
Do not suppress lint with // eslint-disable or @ts-ignore.
- Very specific: line 118
Use exitWithError() from commands/output.ts for structured errors.
- Very specific: line 119
Use requireApiKey() from utils/api-key.ts for required API keys.
- Very specific: line 120
Use hasApiKey() for side-effect-free key detection.
- Very specific: line 121
Use resolveProvider() / provider registry helpers instead of duplicating fallback logic.
- Very specific: line 122
Before changing a provider integration, read its .agents/references/providers/<provider>.md (models, rejected params, deprecation dates) …
- Very specific: line 128
After editing the catalog, run pnpm gen:models (MODELS.md is partly generated).
- Distinctive: line 188
Before pushing from any host, run the shared pre-push gate or enable the repo Git hook:
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
VibeFrame is a frontier-video-generation layer for coding agents: CLI-first,
MCP-ready.
It generates video assets on the user's own provider keys (Seedance, Runway,
Kling, Gemini Omni) behind dry runs and a hard --max-cost ceiling, delegates scene
composition to upstream Hyperframes, and builds the generation, cost, and
review layer around it.
Repository Shape
Monorepo: Turborepo + pnpm workspaces. ESM. TypeScript strict mode.
Packages:
packages/cli- CLI and command implementations.packages/ai-providers- Provider registry and provider implementations.packages/mcp-server- MCP wrapper around the CLI, bundled with esbuild.apps/web- Next.js public site.
Architecture:
CLI (Commander.js) -> Executors (scene projects, one-shot media) -> AI Providers + FFmpeg + HyperframesCommands
pnpm install && pnpm build # Setup
pnpm test # Run all tests
pnpm lint # Lint (0 errors policy)
pnpm -F @vibeframe/cli test # Single packageUse vibe schema --list and vibe schema <command> as the source of truth for
CLI command availability and parameters.
CLI Shape
Canonical user-facing workflows:
- Project video flow:
init,plan,build,preview,render(edit beats withstoryboard, poll async work withstatus) - One-shot media:
generate,edit,inspect,audio,remix - Automation:
run,schema,context,guide - Spend and provenance:
take(the record of every paid generation; seedocs/take-graph.md) - Setup & hosts:
setup,doctor,host - Lower-level operations:
scene,design,detect,media,assemble
Do not introduce docs, examples, or agent instructions that use removed
namespaces such as vibe ai, vibe project, vibe export, vibe pipeline,
vibe timeline, or vibe batch.
Agent Workflow Rules
When invoking VibeFrame commands from an agent context:
- Treat your host's agent loop (Claude Code, Codex, Cursor, or another
coding-agent host) as the outer loop for long-running video work.
VibeFrame should provide video-specific commands, JSON reports, cost gates,
deterministic repair, render inspection, and
nextActions/fixOwnerrecovery contracts, not a competing primary agent loop. - Prefer
--jsonfor structured output. - Run
--dry-runbefore paid or mutating operations when the command supports it. - When a review report includes
nextActions, prefer it over inventing commands: run onlysafeToAutoRun:trueactions automatically, ask beforerequiresConfirmation:true, and treatretryWithas the compatibility fallback. - Use
vibe schema <command>before constructing non-trivial arguments. - Confirm with the user before high/very-high cost operations such as
generate videoand provider-backedremixworkflows. - Use
--stdinfor complex option payloads instead of fragile shell quoting.
Provider assets are inputs, not always the final product. For factual, data-heavy, or typography-heavy videos, prefer deterministic HTML/CSS/JS composition for text, layout, motion, timing, and reviewability.
CLI And Tool Sync
When adding CLI commands, expose them as MCP tools only when natural-language invocation is useful.
Naming: vibe <group> <action> maps to <group>_<action> in snake_case.
Pattern:
- Extract a testable
execute*()function from the command module. - Reuse the same executor from the CLI, the YAML pipeline, and the MCP tool where practical.
- Add a manifest entry (
packages/cli/src/tools/manifest/) with a schema that matches the CLI behavior. - Add focused tests for the executor and wrapper.
Cost Awareness
Do not maintain a separate hardcoded cost table in docs or prompts. The CLI stamps cost tiers on commands; use:
vibe schema --list
vibe schema --list --filter free
vibe schema generate.videoGeneral expectation:
- Free/local: schema, setup/doctor, 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.
Code Quality
- Run
pnpm buildafter TypeScript changes. - Run
pnpm lintafter changes and fix errors before committing. - Do not leave unused imports.
- Do not suppress lint with
// eslint-disableor@ts-ignore; fix the root cause. - Use
exitWithError()fromcommands/output.tsfor structured errors. - Use
requireApiKey()fromutils/api-key.tsfor required API keys. - Use
hasApiKey()for side-effect-free key detection. - Use
resolveProvider()/ provider registry helpers instead of duplicating fallback logic. - Before changing a provider integration, read its
.agents/references/providers/<provider>.md(models, rejected params, deprecation dates) and runpnpm providers:check. - Model IDs, CLI aliases, defaults, lifecycle dates, and list prices live in
the model catalog (
packages/ai-providers/src/catalog/catalog.ts). Read them throughfindModel()/defaultModel(); do not hardcode model IDs. After editing the catalog, runpnpm gen:models(MODELS.md is partly generated). - Video providers implement
VideoGenerator(packages/ai-providers/src/video/) and image providers implementImageGenerator(src/image/): HTTP goes throughproviderRequest, failures areProviderErrors with akind, and each provider passes its contract suite. The CLI opens providers throughcreateVideoGenerator/createImageGeneratorand branches onerror.kind, never on provider names or wording.
Conventions
- Conventional commits:
feat:,fix:,docs:,refactor:,chore:. - Git & PR workflow: branch off
mainasfeat/<topic>,fix/<topic>, orchore/<topic>. One PR = one coherent scope - do not stack unrelated commits onto an open PR branch. Rebase/split when scope drifts. - Every commit reaches
mainvia a PR - includingchore: bump versionrelease commits. Branch → PR → CI green → merge. Do not push directly tomain, even as a maintainer with admin bypass (mainallows it, but the policy does not). Release bumps go on achore/release-<version>(or the feature) branch and merge through the same gate as any other change. - Bump at release time, not per PR.
feat:/fix:PRs merge without a version bump. When you decide to release,/releasebumps once and regeneratesCHANGELOG.mdso the new version covers every commit since the last tag. The push gate warns about unreleased work but never blocks on it; the blocking check lives in.github/workflows/release-tag.yml, which refuses to tag a version that does not describeHEAD. - Version bumps default to
patchduring0.x.patchis the default;minoris rare. Useminoronly for new public CLI command namespaces, new MCP tool families, public API contract additions, or large product milestones; reservemajorfor breaking changes or the 1.0 milestone. The shared push gate (scripts/pre-push-validate.sh) blocks aminor/majorbump unless thechore: bump versioncommit carries aRelease-Type: minor: <reason>(ormajor) trailer, orVIBE_ALLOW_MINOR=1is set. - API keys belong in local config or
.env-style files, never committed. - See
MODELS.mdfor provider details. CHANGELOG.mdis generated withgit-cliff --tag vX.Y.Z -o CHANGELOG.md.- CI never publishes npm packages. Once the version commit lands on
mainand CI passes, the release tag is created automatically by theCreate release tagworkflow. Publishing stays manual: run thePublish to npmworkflow with that tag. (Tags pushed by a workflow cannot trigger another workflow, so auto-tagging never reachespublish.yml.) - Release state is computed in one place -
scripts/release-status.sh. The push gate, the tag workflow, and the daily drift check all call it. Do not reimplement version/tag comparisons anywhere else.
Verification
Match verification to the change:
- TypeScript or command behavior: run
pnpm build,pnpm lint, and focused tests. - CLI schema/reference changes: run
pnpm gen:reference:checkwhen relevant. - Scene/video work: run
vibe scene lint,vibe render, andvibe inspect render --cheap. pnpm testskips the Chrome/CLI-spawning integration tests for speed; runpnpm -F @vibeframe/cli test:integrationwhen touching rendering or scene code (CI always runs them).- Provider or build-pipeline changes: extend the fake provider network
(
packages/cli/src/testing/fake-provider-network.ts) so the real request and file-write path is tested without paid calls.
Before pushing from any host, run the shared pre-push gate or enable the repo Git hook:
pnpm hooks:install
bash scripts/pre-push-validate.shClaude Code's .claude/hooks/pre-push-validate.sh and Git's
.githooks/pre-push both delegate to scripts/pre-push-validate.sh, so Codex,
Claude Code, and direct terminal pushes use the same version/SSOT checks.
Agent Hosts & Sync
vibe init writes one AGENTS.md (plus a CLAUDE.md that imports it) that
serves every bash-capable host; --mcp adds MCP config for Claude Code,
Codex, and Cursor. It does not emit per-host files - projectFiles in
agent-host-detect.ts is a detection list, not a scaffold list. Separately,
pnpm agent-sync keeps three hosts'
generated config (Claude Code, Codex, Cursor) in sync from one canonical source.
Full map + workflows: docs/agent-hosts.md.
- Canonical (edit these):
AGENTS.md(this file - Codex/Cursor read it natively; Claude imports it viaCLAUDE.md=@AGENTS.md) and cross-host skills in.agents/skills/<name>/SKILL.md. - Generated by
pnpm agent-sync(never edit; marked DO NOT EDIT):.claude/skills/*, the MCP block in.codex/config.toml, andmcpServers.vibeframein.cursor/mcp.json. - Claude-only, NOT propagated to Codex/Cursor:
.claude/rules/*(path-scoped),.claude/agents/*,.claude/hooks/*,.claude/settings.json. - Where new guidance goes: shared rules →
AGENTS.mdor.agents/skills/; Claude-only ergonomics →.claude/. Keep this file lean (it loads into every session and is read by every host). - Enforced:
pnpm agent-sync:checkruns in the pre-push gate and CI. After editing a canonical source, runpnpm agent-syncand commit the result.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

