FLMKR — AI Filmmaking Harness

An autonomous, terminal-native AI filmmaking agent that transforms creative ideas into complete audiovisual productions.

What It Is

FLMKR is an agent harness for filmmaking — not a video generator, not a prompt engine, not a GUI wrapper. It's the environment that allows an autonomous agent to perform complex filmmaking work:

• Plan productions from ideas, screenplays, or treatments
• Create and maintain a Production Bible (characters, locations, style, continuity)
• Generate shots through provider-agnostic adapters (Agnes, Kling, MiniMax, Runway)
• Run QA at chunk/shot/scene levels with continuity checking
• Recover from failures without restarting the entire production
• Render final films with editorial assembly

Install

pip install flmkr

Development install (with test & lint tooling):

pip install -e ".[dev]"

Verify:

flmkr --version
# flmkr, version 0.1.0

Quickstart

# Create a new film project from an idea
flmkr create "A woman discovers her autonomous car is taking her somewhere she never asked to go."

# Inspect the auto-generated Production Bible
flmkr bible

# Dry-run the production plan (estimates shots, cost, runtime)
flmkr plan

# Generate all assets
flmkr generate

# View progress
flmkr status
flmkr shots
flmkr events

# Open the interactive TUI to review and approve shots
flmkr review

# Render the final assembled film
flmkr render

# Resume after an interruption
flmkr resume

See docs/getting-started.md for a full 5-minute tutorial.

MCP Usage

FLMKR exposes an MCP server for integration with AI coding agents (Claude Code, Codex CLI, MiMoCode, etc.):

python -m flmkr.mcp_server --project ./my-film

Available tools:

Architecture

┌──────────────────────────────────────────────────────┐
│                    CLI / TUI                         │
│              (click / textual)                       │
└───────────────────────┬──────────────────────────────┘
                        │
┌───────────────────────▼──────────────────────────────┐
│              Producer Orchestrator                     │
│         (flmkr.orchestrator.Orchestrator)              │
│                                                        │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐     │
│  │   Story    │  │ Character  │  │Cinematog-  │     │
│  │   Agent    │  │   Agent    │  │   raphy    │     │
│  └────────────┘  └────────────┘  └────────────┘     │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐     │
│  │ Generation │  │    QA      │  │ Editorial  │     │
│  │   Agent    │  │   Agent    │  │   Agent    │     │
│  └────────────┘  └────────────┘  └────────────┘     │
└───────────────────────┬──────────────────────────────┘
                        │
┌───────────────────────▼──────────────────────────────┐
│              Provider Adapters                       │
│   (Agnes · Kling · MiniMax · Runway · custom)        │
└───────────────────────┬──────────────────────────────┘
                        │
┌───────────────────────▼──────────────────────────────┐
│              Production Bible                        │
│   (Bible → Characters · Locations · Style · Scenes)  │
└───────────────────────┬──────────────────────────────┘
                        │
┌───────────────────────▼──────────────────────────────┐
│              Event Store                             │
│        (SQLite — durable, resumable)                 │
└──────────────────────────────────────────────────────┘

Data Flow

Idea / Screenplay
       ↓
  Project.init()
       ↓
  Bible generation (story, characters, locations, style)
       ↓
  Scene & shot planning
       ↓
  Generation (provider-agnostic, with retry & recovery)
       ↓
  QA (continuity, narrative, technical)
       ↓
  Editorial assembly
       ↓
  Final film render

Project Structure

flmkr/
├── __init__.py      # Package entry
├── cli.py           # Click CLI commands
├── config.py        # Pydantic settings
├── models.py        # Core data models (Bible, Shot, Scene, etc.)
├── agents.py        # Agent framework
├── providers.py     # Provider adapters
├── orchestrator.py  # Producer/Orchestrator
├── qa.py            # QA engine
├── editorial.py     # Editorial/timeline engine
├── project.py       # Project state container
├── event_store.py   # SQLite event log
├── events.py        # Event types
├── exceptions.py    # Error types
├── llm.py           # LLM interaction layer
├── mcp_server.py    # MCP server for AI agent integration
└── tui.py           # Rich terminal UI

Examples

Requirements

• Python 3.11+
• SQLite (bundled with Python)
• Internet connection for provider APIs

License

MIT