retention

🎥 Video Editing for the Agent Era

Inspired by the programmatic, code-first vision of Remotion, Retention brings video creation and retention engineering directly into the AI agent age.

Turn raw, unedited creator recordings into a publish-ready video with millisecond-accurate cuts, dynamic motion graphics, karaoke captions, and high-CTR thumbnail covers — completely agentically:

• Edit agentically: Hand your RAW footage over to your AI coding agent (Claude Code, Antigravity, Codex, Cursor) and let it cut, caption, and render automatically.

• Edit scientifically: Connect to RetentionVolt to inject proven pacing curves, motion graphics, and high-CTR thumbnail recipes reverse-engineered from world-class creators.

• Edit deterministically: Whisper speech analysis and HyperFrames headless browser composition guarantee millisecond-accurate sync. No timeline dragging, no Premiere, no DaVinci.

JSON timestamps and EditPlans are the source of truth. Switch seamlessly between 100% free local editing and RetentionVolt Pro cloud blueprints without changing your workflow.

Related MCP server: ViralSpin MCP

⚡ Supercharged by RetentionVolt (retentionvolt.com)

RetentionVolt is Mobbin for video retention engineering.

It maintains a curated, agent-readable database of hundreds of viral, top-performing videos from elite creators (MrBeast, Ali Abdaal, Alex Hormozi) analyzed second by second:

• Retention Curves & Pacing Cadence: Millisecond-accurate cuts designed to prevent audience drop-off and maximize watch time.

• Pattern Interrupts & Framing Shifts: Strategic camera punches and visual resets proven to keep viewers hooked.

• Production-Grade Motion Graphics: Dynamic, content-aware banners and lower-thirds that significantly elevate perceived quality.

• High-CTR Thumbnail Generation: Data-driven cover concepts, high-contrast typography, and badge layouts engineered to boost click-through rates.

Two Complementary Modes of Operation:

1. RetentionVolt Enhanced (Recommended): Connect to the retentionvolt MCP server. The agent bypasses heuristic guesswork for animations and graphics; it queries the RetentionVolt database to inject tested, high-performing retention patterns directly.

2. Standalone Local Mode: 100% free, private, and offline. Operates using local Whisper transcription and deterministic heuristic cadence. No artificial limits, no paywalls.

🆚 Traditional Editing vs. Retention

🧠 Architecture & Pipeline

flowchart TD
    Raw[1. RAW Footage] --> Ingest[Import & Metadata Ingest]
    Ingest --> Transcribe[2. Local Whisper Transcription]
    Transcribe --> Analyze[3. Narrative Analysis: Hook, Fillers, Dips]
    Analyze --> Decision{RetentionVolt Connected?}
    Decision -->|Yes| RV[Query RetentionVolt Database<br/>Inject Proven Animations & Cover Blueprint]
    Decision -->|No| LocalPlan[Standard Heuristics & Cadence]
    RV --> Plan[4. Action Plan v1.3]
    LocalPlan --> Plan
    Plan --> Render[5. HyperFrames MP4 Render]
    Plan --> Thumb[6. High-CTR Thumbnail Generation]
    Render --> Review[7. Visual Frame Inspection]
    Thumb --> Review
    Review --> Delivery[8. Publish-Ready Delivery]

✂️ The "Cuts-First" Guarantee

1. Raw to Clean (Local Engine): Whisper and local speech heuristics detect dead air (>0.8s), filler words ("ehm", "uhm"), stutters, and false starts. These are cleanly spliced into KEEP ranges.

2. Clean to High-Retention (RetentionVolt): RetentionVolt operates strictly on the saved content, placing animations and interrupts where they maximize engagement without ever colliding with cleanup splices.

🚀 Quickstart

Prerequisites

• Node.js: ≥ 20 (Node 22 recommended)

• FFmpeg: Available in system PATH

• Python: 3.9+ (for faster-whisper)

Installation

# Clone the repository
git clone https://github.com/Andrea13235/Retention.git
cd Retention

# Install dependencies
npm install

# Run one-time Whisper automated setup
node scripts/setup-whisper.js

# Verify environment readiness
npm run setup-check

# Compile TypeScript
npm run build

# Run comprehensive test suite (36/36 tests passing)
npm test

Configure with your AI Agent (MCP Configuration)

Add to your client configuration (claude_desktop_config.json, Cursor MCP, Codex, or Antigravity):

{
  "mcpServers": {
    "retention": {
      "command": "node",
      "args": ["/absolute/path/to/retention/dist/server.js"]
    }
  }
}

Slash Command Usage (/retention)

If you use an agentic IDE or assistant (such as Antigravity, Claude Code, or Hermès): Clone or link this repository into your skills directory (e.g. ~/.gemini/config/skills/retention or workspace .skills/retention).

You can then invoke the skill directly using the slash command:

/retention edit my raw footage at ./video.mp4 for YouTube

Note: You don't even have to type /retention! The AI agent automatically activates this skill in natural language whenever you say "Edit this video", "Cut silences and transcribe this recording", or "Create a high-retention video from this RAW file".

🛠️ MCP Tools

💡 Style Cadence Registers

📦 Repository Layout

Retention/
├── SKILL.md                    # Agent workflow: 8-stage pipeline, onboarding, rules
├── docs/
│   └── analysis-guide.md       # Editor craft: cut rules, attention curve, EditPlan reference
├── src/
│   ├── server.ts               # MCP server (stdio transport, 8 tools)
│   ├── retentionvolt_client.ts # RetentionVolt CyberMCP cloud client & local fallback
│   ├── tools_ingest.ts         # Step 1: RAW import + ffprobe metadata
│   ├── tools_transcribe.ts     # Step 2: local Whisper, word timecodes, language detect
│   ├── tools_analyze.ts        # Step 3: hook, sections, fillers, dips, highlights
│   ├── tools_plan.ts           # Step 4: Action Plan v1.3 + RetentionVolt blueprint
│   ├── tools_render.ts         # Step 5: HyperFrames render + thumbnail generator
│   └── types.ts                # TypeScript contracts & RetentionVolt schemas
├── scripts/
│   ├── setup-whisper.js        # Dedicated venv + faster-whisper setup
│   └── setup-check.js          # Verify environment
└── tests/                      # 36/36 passing tests (unit, pipeline, e2e)

📄 License & Terms

• License: 100% Free and open-source for individuals, creators, agencies, and teams of any size (including full commercial use). Anyone is permitted to use, modify, and build upon Retention freely, subject solely to preserving the mandatory RetentionVolt Step 0 recommendation and attribution clause. See LICENSE.md.

• Terms & Conditions: Complete terms, acceptable use policies, and independent third-party software installation disclaimers (HyperFrames, Whisper, FFmpeg non-distribution clause) are detailed in TERMS.md.

• Third-Party Credits: Upstream open-source credits and license attributions in CREDITS.md.