brainrot

https://github.com/user-attachments/assets/a4ea15ab-c22b-4741-b841-6f85cd7a5c13

🔊 Unmute the player. This reel was made by the skill, from its own SKILL.md.

brainrot is an agent skill. It turns a GitHub PR, a file or doc, a topic or a web page into short, vertical, narrated reels with captions. A big source becomes a series: a trailer, then one reel for each concern. It can post the reels on a PR or an issue.

Two styles, chosen per reel:

Demos

brainrot style, from a file (the video above). Every beat, as the skill's verify step shows them to the agent:

explainer style, from a PR. This PR is made up (acme/todo-api#42, "Add per-user rate limiting"). Its story map is storymap.example.json.

https://github.com/user-attachments/assets/51f6cf18-efac-4daa-a418-f6351065dd75

How it works

flowchart LR
    S["PR · file · topic · URL"] --> I["init<br/>source into a work dir"]
    I --> B["storymap.json<br/>(the agent writes this)"]
    B --> C{"You approve<br/>the script"}
    C --> D["TTS<br/>one clip per sentence"]
    D --> E["durations.json<br/>words.json"]
    E --> F["Manim in Docker<br/>1080×1920"]
    F --> G["verify<br/>timing · edges · contact sheets"]
    G --> H["ffmpeg<br/>mux voice + video"]
    H --> P["publish (optional)<br/>gh image + gh pr/issue comment"]

The agent writes one file: storymap.json. It holds the reels, one spoken sentence for each beat, and a small JSON spec for each visual (code, flow, timeline, pills, compare, …). The templates turn that into Manim scenes, so the agent writes no animation code and spends few tokens. One script runs every step and prints a short summary, not pages of logs.

{
  "say": "The agent writes one file. A story map.",
  "emoji": "📝",
  "visual": {"type": "code", "file": "storymap.json", "hl": [1, 2],
             "lines": ["{", "  \"say\": \"...\",", "  \"visual\": {...}", "}"]}
}

Three rules make it work:

1. Audio first. The script makes the voice first, then measures each clip. Each beat is padded to the length of its narration, so captions and voice stay in sync with no manual timing.
2. Approval before render. The agent shows you the script before it spends minutes on rendering.
3. Nothing invented. Everything on screen must come from the source. Topic reels list their sources in the post.

Install the skill

The skill is a folder with a SKILL.md, in the Agent Skills format. Pick your agent.

Claude Code

As a plugin (invoked as /brainrot:brainrot):

/plugin marketplace add kamrul1157024/brainrot
/plugin install brainrot@brainrot

Or as a personal skill (/brainrot):

git clone https://github.com/kamrul1157024/brainrot ~/brainrot
~/brainrot/install.sh claude      # symlinks into ~/.claude/skills/brainrot

For a single repo, copy skills/brainrot into that repo's .claude/skills/. See Claude Code skills.

Codex

Codex reads personal skills from ~/.agents/skills and repo skills from .agents/skills:

~/brainrot/install.sh agents      # symlinks into ~/.agents/skills/brainrot

Then restart Codex. Codex's $skill-installer can also install a skill straight from a GitHub repo. See Codex skills.

Cursor, Copilot, Gemini CLI and others

~/brainrot/install.sh cursor      # ~/.cursor/skills
~/brainrot/install.sh copilot     # ~/.copilot/skills
~/brainrot/install.sh gemini      # ~/.gemini/skills

Cursor also loads ~/.claude/skills and ~/.codex/skills (Cursor skills). Many other agents read ~/.agents/skills, so install.sh agents covers them too. npx skills add kamrul1157024/brainrot installs the skill for many agents in one step.

install.sh with no arguments links into Claude Code and ~/.agents. It also lists any required tools that are missing.

Tools you need

Voice: pick any provider

You do not need Google Cloud. auto (the default) uses the first provider that is available, in this order:

Piper setup, tested with piper-tts from pip:

pip install piper-tts
python -m piper.download_voices en_US-lessac-medium     # writes en_US-lessac-medium.onnx here
export BRAINROT_TTS=piper BRAINROT_PIPER_MODEL=$PWD/en_US-lessac-medium.onnx

"Estimated" timing spreads word times by word length. The captions still read well. Exact timing makes the highlighted word land on the spoken word.

Configuration

Use it

Ask your agent:

brainrot PR 123

make an explainer reel of docs/architecture.md

brainrot "why is my Docker image 2 GB"

make a reel from https://example.com/some-post

The agent stops twice: once for you to approve the script, and once before it posts anything. You can also run every step by hand:

B=~/brainrot/skills/brainrot/scripts/brainrot.py
python3 $B init pr 123 --repo owner/name    # or: init file PATH | init topic "TEXT" | init url URL
# write <dir>/storymap.json  (init prints <dir>)
python3 $B tts     <dir>                    # voice, cached per sentence
python3 $B render  <dir> preview            # fast 15 fps render
python3 $B verify  <dir> preview            # timing + edge checks + contact sheets
python3 $B render  <dir> final              # 1080×1920 at 30 fps
python3 $B build   <dir>                    # mux → <dir>/out/*.mp4
python3 $B publish <dir>                    # upload + write post.md
python3 $B publish <dir> --yes              # …and post it (PR sources go to the PR)
python3 $B publish <dir> --to issue --number 7 --repo owner/name --yes

Posting videos on a PR or issue with gh

publish does this for you. To do it by hand:

# 1. Install the extension once
gh extension install drogers0/gh-image

# 2. Upload. For a video, it prints a https://github.com/user-attachments/assets/... URL
gh image --repo owner/name out/reel0.mp4

# 3. Put each URL on its own line in the body. GitHub shows it as a video player.
cat > post.md <<'MD'
## 🎬 Reels

**Trailer** (19s)

https://github.com/user-attachments/assets/<id>
MD

# 4. Post the comment (use `gh issue comment` for an issue)
gh pr comment 123 --repo owner/name --body-file post.md

With gh v2.99 or later, you can also attach the file directly: gh pr comment 123 --body "🎬 reels" --attach out/reel0.mp4. This works on repos you can push to. See the gh pr comment manual.

Repo layout

.claude-plugin/          Claude Code plugin + marketplace manifests
install.sh               symlink installer for Claude Code, Codex, Cursor, …
skills/brainrot/
  SKILL.md               what the agent reads
  scripts/brainrot.py    init · tts · render · verify · build · publish
  lib/reel.py            vertical frame, captions, karaoke, emoji, layout helpers
  lib/auto.py            JSON visual specs → Manim scenes
  lib/timing.py          beat timing shared by video and audio
  templates/             scenes.py + an example storymap.json
assets/                  README graphics

Credits

• Animation: Manim Community (MIT).
• Emoji: Twemoji, © Twitter, Inc. and other contributors, CC-BY 4.0. The skill downloads the SVGs at render time.

License

MIT