# CapCut AI editor setup specification

Version: 1.0
Last verified: 2026-09-17
Audience: coding agents and technical operators
Human guide: https://suheilai.com/blog/claude-capcut-ai-editor-open-source-arabic
Source video: https://www.youtube.com/watch?v=Lc9_FGfatNo

## Purpose

Install and verify the open-source toolkit that lets a coding agent edit native local CapCut projects on macOS without flattening the result into one rendered video. The final deliverable remains editable in CapCut.

This project is unofficial and is not affiliated with, endorsed by, or sponsored by ByteDance, CapCut, or Lemon Inc. CapCut's draft format is undocumented and may change.

## Verified repositories

- CLI: https://github.com/RoXsaita/capcut-editor-cli
- Skills: https://github.com/RoXsaita/capcut-skills
- CLI stable release at verification: `v0.1.1`
- License: MIT in both repositories
- Default branch: `main` in both repositories
- CLI CI: passing on the verified main commit
- Skills CI: passing on the verified main commit

Clone with HTTPS unless the user already has working SSH authentication:

```bash
mkdir -p ~/src
cd ~/src
git clone https://github.com/RoXsaita/capcut-editor-cli.git
git clone https://github.com/RoXsaita/capcut-skills.git
```

## System requirements

- macOS
- CapCut Desktop installed and launched at least once
- Git
- Node.js 20 or newer
- Python 3.11 or newer
- ffmpeg and ffprobe
- Enough free disk space for source media, snapshots, QA frames, and optional proxies

Homebrew dependency command:

```bash
brew install node python@3.11 ffmpeg
```

Do not use `sudo` to force an install. Do not install CapCut from an unofficial source.

## Project architecture

`capcut-editor-cli` owns runtime behavior:

- `bin/capcutctl.mjs`: executable entry point
- `src/`: command routing, project transactions, layouts, media operations, QA, matching, pacing, audio, and export helpers
- `tools/`: Python and Swift helpers for A-roll analysis, OCR, frame QA, media indexing, and verification
- `presets/`: portable project and style defaults
- `assets/`: bundled layout artwork
- `docs/cli-contract.json`: machine-readable command and option contract
- `test/`: synthetic project and media regression suite

`capcut-skills` owns agent operating instructions:

- `capcut-cli`: command surface and safety model
- `capcut-editing`: hub, native-editability rules, format, and project state
- `capcut-editing-talking-head`: A-roll selection, acoustic boundaries, and layouts
- `capcut-editing-screen-recording`: B-roll indexing, OCR matching, and proof selection
- `.capcut/cli-contract.json`: vendored CLI contract used to validate documented commands
- `scripts/validate.py`: skill, link, and CLI-command validator

There is no server, database, account, OAuth flow, or public API required. The tool operates on local CapCut project files.

## Install the CLI

```bash
cd ~/src/capcut-editor-cli
npm link
python3.11 -m venv .venv
.venv/bin/python -m pip install -e .
```

If `npm link` requires elevated permissions, do not use `sudo`. Use the user-local symlink method from the repository's `SETUP.md` and confirm `~/.local/bin` is already on PATH before changing shell configuration.

## Install the skills

Detect the active agent's skills root. Do not guess for an unknown runtime.

Known defaults:

- Codex: `${CODEX_HOME:-$HOME/.codex}/skills`
- Claude Code: `$HOME/.claude/skills`
- Hermes: configured root under `$HOME/.hermes/skills`

Symlink these four directories and preserve any existing destination:

```bash
cd ~/src/capcut-skills
agent_skills="${CODEX_HOME:-$HOME/.codex}/skills"
mkdir -p "$agent_skills"
for skill in capcut-cli capcut-editing capcut-editing-talking-head capcut-editing-screen-recording; do
  if [ -e "$agent_skills/$skill" ] || [ -L "$agent_skills/$skill" ]; then
    printf 'Skipped existing skill: %s\n' "$agent_skills/$skill"
    continue
  fi
  ln -s "$PWD/$skill" "$agent_skills/$skill"
done
```

Replace `agent_skills` with the verified root for Claude Code, Hermes, or another runtime.

## Environment variables

No secret is required for the core editor.

- `CAPCUTCTL_PYTHON`: optional explicit Python 3.11+ interpreter
- `CAPCUTCTL_PRESET_DIR`: optional user-owned preset directory
- `CAPCUTCTL_ASSET_DIR`: optional user-owned overlay artwork directory
- `GEMINI_API_KEY`: optional, only for the Gemini/Lyria music feature

Never commit `.env`, keys, tokens, private media paths, transcripts, or QA frames.

## Safety contract

1. Do not hand-edit `draft_info.json` when `capcutctl` can express the operation.
2. Close CapCut before writes. Never use `--force-running` as a routine shortcut.
3. Keep backups enabled. Every committed transaction should snapshot, validate, synchronize mirrors, and roll back on failed post-write validation.
4. Use full-frame durable source media. Do not import pre-cropped media or temporary scratch files unless the command explicitly records provenance.
5. Run `--dry-run` before the first write of a new operation.
6. Start on a copied or disposable project.
7. Run `capcutctl doctor` after writes. Use `qa` for pixel-level proof and native CapCut playback for the final human review.
8. Before the first project write, ask the user to choose bundled example style, harvest their own drafts, or start blank.

## Acceptance checks

Run exactly these checks and preserve nonzero exits:

```bash
cd ~/src/capcut-editor-cli
npm test
capcutctl version
capcutctl preflight
capcutctl projects
capcutctl contract
cd ~/src/capcut-skills
python3 scripts/validate.py
python3 scripts/test_validate.py
```

Setup passes only when:

- `capcutctl` resolves without elevated privileges;
- Node.js and Python meet the minimum versions;
- ffmpeg and ffprobe are available;
- the CLI test suite passes;
- both skills validators pass;
- all four skill links resolve to the cloned repository;
- `preflight` says ready or reports a clearly identified manual prerequisite;
- no real CapCut project was modified during setup.

Missing machine-local SFX may be reported as an optional degradation. Missing CapCut, Python, ffmpeg, the drafts directory, or a writable safe install path is a blocker.

## Safe first-edit order

1. Duplicate or create a disposable CapCut project.
2. Ask the user to select the style mode.
3. Inspect with `capcutctl scenes` and `capcutctl doctor`.
4. Snapshot the project.
5. Close CapCut.
6. Run the intended command with `--dry-run`.
7. Review the planned change.
8. Run the committed transaction.
9. Run `capcutctl doctor`.
10. Open CapCut and review the editable timeline before export.

## Recovery

- List snapshots with `capcutctl history --project NAME`.
- Inspect changes with `capcutctl diff --project NAME --snapshot SNAPSHOT`.
- Restore only a verified snapshot with `capcutctl restore --project NAME --snapshot SNAPSHOT`.
- If a repository clone is dirty, do not reset or overwrite it. Stop and report the changed paths.
- Report security issues privately through the CLI repository's GitHub Security Advisory form.

## Copyable agent prompt

The canonical copyable prompt is available at:

https://suheilai.com/blog/claude-capcut-ai-editor-open-source-arabic/AGENT-SETUP-PROMPT.md

It instructs the agent to inventory the Mac, clone both repositories safely, install the CLI without `sudo`, detect the active skills root, install all four skills without overwriting existing work, run the full verification ladder, avoid touching real projects during setup, and return a redacted installation report.