Plotloom

AI short-drama production CLI | Agent-neutral Skills | Repo-first workflow

Plotloom is a CLI + Skills toolkit for AI short-drama production. Instead of hiding the production process inside a database, dashboard, or queue, it writes every step into readable, committable, and reviewable series repo files: series.md, characters.md, video-prompts.md, candidate media, selected.mp4, and final delivery artifacts.

Core Components

Stage	Default capability
Series planning	Plotloom skills generate series settings, character settings, and episode cards
Image assets	Local Codex image generation for characters, scenes, covers, and references
Video generation	Dreamina/Jimeng CLI, VolcEngine Seedance 2.0, and mock adapter
Selection and delivery	Candidate management, `selected.*` locking, review artifacts, and ffmpeg/ffprobe checks

Plotloom is not a one-click black-box generator. It helps agents and humans collaborate around the same repo by splitting short-drama production into clear, reviewable, and replayable file boundaries.

Overview

Plotloom does not send an idea directly to a model and wait for an opaque final video. It turns short-drama production into a reviewable repo-first pipeline: define the series, character relationships, and visual anchors first; generate image and video candidates around each episode; let humans or agents select, rerun, and revise prompts; then stitch only confirmed assets into the final delivery.

Each step has an explicit file boundary:

series.md / characters.md: long-term series memory and character consistency anchors.
episode-card.md: episode hook, twist, emotional target, and cliffhanger.
video-prompts.md / video-prompts-en.md: clip tasks that can be submitted to Dreamina, Seedance, and other providers.
reference-map.toml: explicit first/last frame, character, scene, prop, and other reference intent.
candidates/: image or video candidates generated by models.
selected.*: the accepted version after review.
tasks/*.toml: provider requests, task status, receipts, prompt hashes, and QA checklists.
review/ / selected-note.md: candidate review materials, extracted frames, media facts, and selection reasons.
final.mp4: the final delivery video stitched from selected clips.

Recommended Clients

Client	Status
Codex	Adapted for CLI + skills collaboration
Claude Code	Usable through skills installation
Other clients that support skills.sh	Install through the client's skills workflow

Plotloom is agent-neutral by design. The CLI is not bound to one specific agent, and the skills use file contracts instead of hidden state whenever possible.

Install CLI

Option 1: uvx, recommended and no install required

uvx plotloom --help

Option 2: pip, global install

pip install plotloom
plotloom --help

Option 3: local development mode

git clone https://github.com/T0UGH/plotloom.git
cd plotloom
pip install -e .
plotloom --help

To run development tests:

uv sync --extra dev
uv run pytest

Install Skills

Plotloom skills are best installed through the skills CLI:

npx skills add T0UGH/plotloom --all

Common variants:

# Project-level install, with interactive agent selection
npx skills add T0UGH/plotloom

# Global install into supported agents
npx skills add T0UGH/plotloom --global --all

# Install one skill only
npx skills add T0UGH/plotloom --skill plotloom-shot-prompts --all

# List installable skills only
npx skills add T0UGH/plotloom --list

For local development, install from the repository root:

npx skills add . --list
npx skills add . --all

Quick Start

# 1. Initialize local config
plotloom config init

# 2. Create a short-drama series repo
plotloom init neon-heiress --title "Neon Heiress"

# 3. Enter the default repo location
cd ~/plotloom_repo/neon-heiress

# 4. Add a testable prompt
cat > episodes/ep001/video-prompts-en.md <<'EOF'
## Clip 01

Prompt string:
A 5-second vertical short-drama opening. A young heiress walks into a neon-lit hotel lobby, calm but dangerous.
EOF

# 5. Generate a local mock video candidate without calling a real provider
plotloom --repo . video submit --episode ep001 --clip clip-01 --adapter mock

# 6. Select the candidate
plotloom --repo . select episodes/ep001/videos/clip-01/candidates/v001.mock.mp4

# 7. Validate repo state
plotloom --repo . validate --require-prompts --require-media

Key generated files:

episodes/ep001/video-prompts-en.md
episodes/ep001/videos/clip-01/candidates/v001.mock.mp4
episodes/ep001/videos/clip-01/selected.mp4
episodes/ep001/videos/clip-01/tasks/mock-local.toml

Create with Skills

The recommended Plotloom workflow is to let an agent call skills stage by stage instead of completing everything in one opaque pass. Use series, episode, and prompt skills to turn intent into stable files first; then use adapter, selection, and delivery skills to produce, review, and deliver media assets.

Recommended order:

1. plotloom-series-brainstorming       -> brainstorm and align the series direction, then stabilize characters and visual anchors
2. plotloom-character-reference-sheet  -> generate production-grade character brief/prompt/reference sheet
3. plotloom-episode-card               -> define episode hook, twist, and cliffhanger
4. plotloom-shot-prompts               -> generate continuous video prompts
5. plotloom-video-adapter              -> submit mock / Dreamina / Seedance video candidates and record receipts
6. plotloom-asset-selection            -> accept, review, reroll, or revise_prompt
7. plotloom-stitch-deliver             -> stitch selected clips and prepare delivery files
8. plotloom-subtitle-burnin            -> add English / Chinese / bilingual subtitles and validate burn-in output

Skill List

Skill	Description
`plotloom-series-brainstorming`	Use heuristic discussion to converge on a series direction and create or update `series.md` and `characters.md`
`plotloom-character-reference-sheet`	Generate production-grade character reference sheet briefs/prompts: turnaround, palette, expressions, micro-expressions, outfits, props, and gestures
`plotloom-episode-card`	Generate a lightweight episode intent card
`plotloom-shot-prompts`	Generate continuous video prompts suitable for Seedance and Dreamina
`plotloom-video-adapter`	Plan reference maps, submit, or poll mock, Dreamina, and VolcEngine video tasks
`plotloom-asset-selection`	Review candidate assets and lock them as `selected.*`, with optional selection reasons and continuity artifacts
`plotloom-stitch-deliver`	Stitch `final.mp4` with local media tools and organize delivery files
`plotloom-subtitle-burnin`	Generate English / Chinese / bilingual subtitles from the final video, burn them in, and validate decoding and frame extraction

Supported Providers

Adapter	Type	Use	Notes
`mock`	Local video	Local E2E, tests, and demos	Does not call any real provider
`codex-app-server`	Image	Character, scene, cover, and reference images	Requires local Codex and image generation capability
`dreamina-cli`	Video	Dreamina/Jimeng video generation	Requires local Dreamina CLI login state
`volcengine-seedance`	Video	VolcEngine Ark Seedance 2.0	Submits and polls through Ark async task API
`youtube-shorts`	Delivery	Upload final short videos to YouTube Shorts	Requires local OAuth credentials

Before using a real provider, run doctor and then a single short-clip smoke test:

plotloom doctor --adapter dreamina-cli --deep
plotloom doctor --adapter volcengine-seedance --deep
plotloom config doctor --adapter volcengine-seedance

More smoke steps are documented in Plotloom Provider Smoke Runbook. Adapter and host notes are indexed in docs/README.md.

CLI Commands

Command	Description
`plotloom init`	Initialize a series repo
`plotloom validate`	Check required files and media state for a series repo
`plotloom config`	Manage `~/.plotloom/.env.toml` config
`plotloom repos`	Manage the local series repo registry
`plotloom prompt`	Check, extract, and compile episode prompts
`plotloom image`	Generate and archive image candidates
`plotloom video`	Plan references, submit, poll, and compare video generation tasks
`plotloom asset`	Import and inspect local assets
`plotloom face`	Check character face policy and generate provider smoke prompts
`plotloom review`	Generate image contact sheets, video review artifacts, and selected notes
`plotloom select`	Copy a candidate asset to `selected.*`, with optional selection reason
`plotloom media`	Run local media probe, check, and normalize operations
`plotloom stitch`	Plan or stitch selected clips
`plotloom delivery`	Summarize delivery files
`plotloom youtube`	Perform OAuth login and upload YouTube Shorts
`plotloom doctor`	Check local adapter, dependency, and config state

View complete parameters:

plotloom --help
plotloom prompt compile --help
plotloom video plan-references --help
plotloom video submit --help
plotloom image generate --help
plotloom review media --help

Reference, Prompt, and Review Workflow

For production work, keep reference intent, provider prompts, candidate review, and selection results explicit:

# Write reference-map.toml for one clip. Paths can be repo-relative or local file paths.
plotloom --repo . video plan-references \
  --episode ep001 \
  --clip clip-01 \
  --first-frame assets/scenes/hotel-lobby/selected.png \
  --reference "character:hero=assets/cast/hero/selected.png" \
  --write

# Compile a provider prompt into auditable text, including source_prompt_sha256 and qa_checklist
plotloom --repo . prompt compile \
  --episode ep001 \
  --clip clip-01 \
  --adapter volcengine-seedance \
  --mode image-to-video \
  --reference-map episodes/ep001/videos/clip-01/reference-map.toml \
  --lint \
  --output episodes/ep001/videos/clip-01/compiled-prompt.txt

# Submit a video task. The reference map is included in request summaries and receipts.
# Provider-level reference support depends on the adapter.
plotloom --repo . video submit \
  --episode ep001 \
  --clip clip-01 \
  --adapter volcengine-seedance \
  --mode image-to-video \
  --reference-map episodes/ep001/videos/clip-01/reference-map.toml

# Generate ffprobe, volumedetect, first/last frames, and REVIEW.md for a video candidate
plotloom --repo . review media \
  --episode ep001 \
  --clip clip-01 \
  --candidate v001

# Accept a candidate and record the human selection reason
plotloom --repo . select \
  episodes/ep001/videos/clip-01/candidates/v001.mp4 \
  --reason "identity and story beat passed"

prompt check --strict-refs can align prompt slots such as Image 1 / Image 2 / 图片 1 with reference-map.toml and fail on mismatches. Plotloom does not automatically generate large candidate batches by default. Multi-candidate exploration must be explicitly triggered by a human or an upper-level agent to avoid unintended real-provider cost.

Configuration

The default Plotloom config file is:

~/.plotloom/.env.toml

Initialize it with:

plotloom config init
plotloom config path

The default template includes:

[plotloom]
repos_root = "~/plotloom_repo"
registry_path = "~/plotloom.toml"
default_image_adapter = "codex-app-server"
default_video_adapters = ["dreamina-cli", "volcengine-seedance"]

[adapters.codex-app-server]
enabled = true
codex_binary = "codex"
app_server_url = ""

[adapters.dreamina-cli]
enabled = true
binary = "dreamina"
home = "~"

[adapters.volcengine-seedance]
enabled = true
ark_api_key = ""
base_url = "https://ark.cn-beijing.volces.com/api/v3"
model = "doubao-seedance-2-0-260128"
default_resolution = "720p"

[adapters.youtube-shorts]
enabled = true
client_secrets_file = "~/.plotloom/youtube-client-secrets.json"
credentials_file = "~/.plotloom/youtube-credentials.json"
default_privacy = "public"

A series repo can also enable optional video continuity artifacts in its own plotloom.toml. This is disabled by default. When enabled, plotloom select extracts the configured first and/or last frame from the selected video and writes selected-note.md, but it does not automatically submit the previous clip's last frame to a provider:

[video.continuity]
enabled = true
extract_first_frame = true
extract_last_frame = true
auto_use_previous_last_frame = false

Environment Variable Overrides

Environment variable	Config field
`PLOTLOOM_CONFIG`	Config file path
`PLOTLOOM_REPOS_ROOT`	Override default series repo root
`PLOTLOOM_REGISTRY_PATH`	Override registry path
`CODEX_BINARY`	Override Codex binary
`CODEX_APP_SERVER_URL`	Override Codex app server URL
`DREAMINA_BINARY`	Override Dreamina CLI binary
`DREAMINA_HOME`	Override Dreamina home
`ARK_API_KEY`	VolcEngine Ark API Key
`PLOTLOOM_VOLCENGINE_BASE_URL`	Override VolcEngine base URL
`PLOTLOOM_VOLCENGINE_MODEL`	Override Seedance model
`YOUTUBE_CLIENT_SECRETS_FILE`	Override YouTube OAuth client secrets path
`YOUTUBE_CREDENTIALS_FILE`	Override YouTube OAuth credentials path
`YOUTUBE_DEFAULT_PRIVACY`	Override YouTube default privacy

Config precedence:

environment variables > ~/.plotloom/.env.toml > built-in defaults

Plotloom doctor only reports whether secrets exist. It does not print secret values.

Series Repo Structure

series.md
characters.md
plotloom.toml
assets/
  cast/
  scenes/
episodes/
  ep001/
    episode-card.md
    video-prompts.md
    video-prompts-en.md
    images/
    videos/
      clip-01/
        candidates/
        tasks/
        reference-map.toml
        review/
        selected.mp4
        selected-note.md
outputs/

This structure is Plotloom's main state boundary: agents can read and write it, humans can review it, and Git can track it.

Design Boundaries

Plotloom currently does not:

include an internal database
maintain hidden workflow state
provide a dashboard
run a background queue worker
consume real provider quota in bulk by default
use Feishu/Lark as the state center
require a full script, storyboard table, or director's treatment

The MVP principle is prompt-first, repo-first, adapter-thin.

Development

# Install development dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Build and dry-run package publish
uv build
uv publish --dry-run --check-url https://pypi.org/simple/ dist/*

Before publishing a new version, bump the version in pyproject.toml; PyPI does not allow overwriting an already published package version.

Tagline

Weave short dramas from sparks.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Plotloom

Core Components

Overview

Recommended Clients

Install CLI

Option 1: uvx, recommended and no install required

Option 2: pip, global install

Option 3: local development mode

Install Skills

Quick Start

Create with Skills

Skill List

Supported Providers

CLI Commands

Reference, Prompt, and Review Workflow

Configuration

Environment Variable Overrides

Series Repo Structure

Design Boundaries

Development

Tagline

FilesExpand file tree

README_EN.md

Latest commit

History

README_EN.md

File metadata and controls

Plotloom

Core Components

Overview

Recommended Clients

Install CLI

Option 1: uvx, recommended and no install required

Option 2: pip, global install

Option 3: local development mode

Install Skills

Quick Start

Create with Skills

Skill List

Supported Providers

CLI Commands

Reference, Prompt, and Review Workflow

Configuration

Environment Variable Overrides

Series Repo Structure

Design Boundaries

Development

Tagline