Brainrotten

AI coding agents change your code faster than you can read it. Brainrotten turns what your agent just did into a one-minute video you would actually watch: a hand-drawn diagram, two cartoon characters arguing it out, a code review, a ranking, or the parts of your system texting each other. The video stops to ask you what happens next, and ends with a short quiz, so you understand the change instead of just accepting it.

It works in English, Hinglish and Benglish, and the first five videos on the website are free.

Try it on the website · Watch the examples · Connect your coding agent

How it works

1. You work with your coding agent as usual (Claude Code, Codex, Cursor, Kiro, VS Code and others).

2. Ask it to explain what it did. It already knows the change and the reasons, so it writes the script itself and picks the best format.

3. Brainrotten draws it, voices it and renders the video in the background while your agent keeps working.

4. You watch it, answer the questions and keep the notes, transcript and flashcards.

Related MCP server: MCP Walkthrough

Five ways to explain a change

Twelve example sessions, beginner to advanced, across Python, JavaScript, Go, Rust, Flutter, Kubernetes and more, in English and Hinglish. All of them are on the examples page.

Videos can pause for Pause & Predict: the screen asks what happens next, gives you a few seconds to think, then shows the answer.

Get started

On the website

Open the website, sign in with Google, type a topic or paste an error, pick a format and press Generate. Five videos per account are free.

Connect your coding agent

Paste this into your terminal (needs Node.js 20 or newer):

npx -y brainrotten-mcp@latest setup

It opens Google sign-in in your browser, then adds Brainrotten to every coding agent on your computer: Claude Code, Codex, Antigravity, Cursor, VS Code, Claude Desktop, Windsurf, Kiro, Gemini CLI, GitHub Copilot CLI, Zed, Cline, OpenCode, Goose and more (20+ agents, on macOS, Windows and Linux). Your other settings are kept, with a backup of every file it changes. Restart your agent, then ask:

Explain what we just did as a Brainrotten video.

Prefer not to touch the terminal? Tell your agent: "Install Brainrotten MCP from https://d3sk6lwsh4ufyv.cloudfront.net/install.md". It can do the whole setup, including signing you in.

On a machine without a browser, add --no-login; your agent can then call the sign_in tool, which gives you a link to open anywhere.

For developers

What's inside

flowchart LR
  A[Coding agent] -- MCP / Python SDK --> B[Brainrotten API]
  S[Studio website] -- REST --> B
  P[Android app] -- REST --> B
  B -- queue --> W[Render worker]
  W --> T[Script check]
  W --> V[ElevenLabs voices]
  W --> R[Satori + resvg frames]
  R --> F[FFmpeg MP4 + learning pack]

apps/
  companion/     Local server (Express + SQLite on 127.0.0.1:3001), the stdio MCP server and the brainrotten-mcp installer
  web/           Website and Studio (React + Vite)
  cloud/         Hosted backend: Lambda API and render worker (container image)
packages/
  contracts/     Zod schemas every client shares: requests, formats, jobs, learning packs, sessions
  core/          Repository evidence and lesson helpers
  media/         Script checks, voices, frame rendering (Satori + resvg, rough.js) and FFmpeg composition
sdk/python/      The MCP tools as Python functions
infra/
  sam/           API stack: API Gateway, Lambda, SQS, DynamoDB, S3, Cognito
  site/          Website stack: private S3 bucket behind CloudFront
  ci/            Keyless GitLab CI deploy role (OIDC) and the private media bucket
assets/          Where third-party media goes locally: not in git (see assets/README.md)
scripts/         Build, release and deploy scripts (scripts/ci for the pipeline)
tools/           Optional local voice model
examples/        Test fixtures

Use it from code

• REST API: https://fqfewiusg8.execute-api.ap-south-1.amazonaws.com/api/v1 with a Cognito access token. OpenAPI spec at /openapi.json; every format's rules and a complete example at GET /formats/guide?format=sketch.

• Python SDK: pip install ./sdk/python, then Brainrotten(account=True).make_video(request) validates, generates, waits and returns a small summary. See sdk/python/README.md.

• Mobile: ANDROID-INTEGRATION.md covers sign-in and every endpoint; BRAINROTGRAM.md is the full spec for the BrainRotGram Android app. The app itself lives in a separate repository; pnpm app:sync updates the default branch in ../brainrotgram, checks its API calls and sign-in settings against the live backend, verifies canonical contract fixtures, and runs flutter analyze and flutter test. Use pnpm app:sync --no-pull for local feature work, or --skip-flutter for API/auth checks only. After pnpm build, node scripts/app-contract-fixtures.mjs refreshes the synthetic Android fixtures for coordinated contract changes.

Run it locally

You need Node.js 26+, pnpm 9+ and FFmpeg.

The repository holds code only. Character cutouts, voices, gameplay clips and example videos are third-party media, kept in a private bucket; maintainers fetch them with pnpm media:pull (needs AWS access). Without them everything builds and the tests pass; videos need your own characters and background clips in assets/ (see assets/README.md).

pnpm install
cp .env.example .env      # add ELEVENLABS_API_KEY and a script provider key (Gemini or Paper)
pnpm build
pnpm dev                  # Studio at http://127.0.0.1:3001/studio

Tests never call paid services or use real keys.

Deploys and releases

Deploy from your own computer with your AWS login: pnpm deploy:site (website) and pnpm deploy:backend (API and worker; needs Docker).

Operations. Every API response carries an x-request-id header; errors are JSON {code, message, retryable, requestId} with standard status codes (400 malformed JSON, 401 (a missing or invalid token is rejected by API Gateway itself, whose fixed body is only {"message":"Unauthorized"}; treat any 401 as "sign in again"), 403 trial limit, 404, 409 version conflict, 413, 415, 422 validation, 429, 5xx), as documented in the OpenAPI spec. API Gateway writes one JSON access-log line per request; both Lambdas are traced with X-Ray; the worker logs one metric line per video (Brainrotten namespace: JobSucceeded, JobFailed, JobSeconds, QueueWaitSeconds). Alarms cover dead-letter messages, queue backlog over 15 minutes, worker and API crashes, API 5xx and repeated video failures; get them by email with ALERT_EMAIL=you@example.com pnpm deploy:backend (confirm the AWS email once). pnpm ops:status summarizes the queue and the last day's outcomes; pnpm ops:refund <jobId> returns a free video for a job stuck on hold.

The same steps can also run in GitLab CI: every push and merge request runs the checks (.gitlab-ci.yml). On main, website changes go live automatically. Backend changes build the Lambda image straight away and go live when you press play on the deploy-backend job (about 20 seconds for code-only changes). GitLab signs in to AWS with OIDC, so no AWS keys are stored anywhere. One-time setup: scripts/ci/bootstrap.sh.

To release the installer, bump the version in apps/companion/package.json, push to main, then run Actions → Publish MCP installer to npm on GitHub. It publishes brainrotten-mcp to npm through Trusted Publishing with provenance; there are no GitHub Releases.

Credits and license

Brainrotten is an unofficial, non-commercial fan project. The cartoon characters (from Oggy and the Cockroaches, Motu Patlu and Bandbudh Aur Budbak) and the gameplay footage belong to their owners, and the character voices are AI clones: the original actors did not say these lines. Full credits, including fonts, icons and emoji, are in NOTICE.md.

The code is released under the MIT License. That license does not cover the third-party characters, voices, footage or fonts.

Questions and ideas: issues. Mirror: gitlab.com/wdipak/brainrotten.