brainrot wires into your coding agent, opens a real short-form feed or a local fake feed while the agent is actively working, then hides the browser and returns focus when the run finishes.
After setup, the normal flow is simple:
- run
/brainrotonce to arm it - start coding with your agent
- brainrot opens only while the agent is working
- brainrot hides when the run ends
- the same live session is resumed later when possible
If your coding agent can read a GitHub repo, the easiest path is often just giving it this repo:
https://github.com/deepmroot/brainrot
Or copy/paste this:
Install brainrot from https://github.com/deepmroot/brainrot.
If Claude Code, Gemini CLI, or Codex is installed on this machine, use the standard installer from the repo.
If pi is installed, copy agents/brainrot.md to ~/.pi/agent/skills/brainrot/SKILL.md and then run node bin/install.js.
After install, show me the exact /brainrot commands I should use.
Short version:
- supported agents can usually install from the repo directly
- pi currently uses the same shared runtime, plus a manual skill copy
AGENTS.mdin this repo is written for coding agents and can be used as the source of truth
Most agent-side "waiting mode" ideas stop at one of these:
- a browser window that always opens from scratch
- a fake overlay with no real provider support
- a one-off hook script that breaks once setup gets more complex
brainrot exists to make that experience feel like a real product instead of a gimmick.
It is built around four practical goals:
- support real coding agents, not one custom fork
- support real providers, not just a mock overlay
- preserve browser state and provider login between runs
- stay opt-in, controllable, and easy to disable
That is why the project includes:
- agent-specific install wiring
- a persistent local daemon
- per-provider browser profiles
- arm/live/resume behavior instead of always-open behavior
- real-provider setup flow plus a local preview mode
| Metric | Value |
|---|---|
| Documented agent integrations | 4 |
| Built-in providers | 5 |
| Hook points used | 2 |
| Daemon port | 9346 |
| Persistent profile buckets | provider + site override |
| Default idle autoscroll delay | 8 seconds |
- opens TikTok, YouTube Shorts, Instagram, X, or a local fake feed
- runs only while your agent is actually working
- keeps one persistent browser profile per provider
- supports first-time login flow for real providers
- hides the browser instead of always destroying it, so the same live session can be resumed later
- supports idle-based autoscroll for real provider pages
- tries to refocus your work window when the agent finishes
| Capability | brainrot | Plain hook script | Basic browser opener | Fake feed only |
|---|---|---|---|---|
| Claude Code support | yes | partial | no | partial |
| Gemini CLI support | yes | partial | no | no |
| Codex support | yes | partial | no | no |
| pi support | manual | partial | no | partial |
| Guided first-time setup | yes | no | no | yes |
| Real providers | yes | maybe | yes | no |
| Persistent per-provider profiles | yes | no | maybe | no |
| Armed state for next run | yes | no | no | no |
| Hide and resume same live session | yes | no | no | no |
| Idle autoscroll | yes | no | no | no |
| Shorts playback kickstart | yes | no | no | no |
| Local fake feed | yes | no | no | yes |
| Agent | Integration method | Result |
|---|---|---|
| Claude Code | ~/.claude/settings.json hooks + Claude skill |
Full /brainrot workflow |
| Gemini CLI | ~/.gemini/GEMINI.md instructions |
Agent can call brainrot hooks |
| Codex | ~/.codex/AGENTS.md instructions |
Agent can call brainrot hooks |
| pi | manual skill install to ~/.pi/agent/skills/brainrot/SKILL.md |
Manual skill-style install documented below |
What the installer changes
- merges
PreToolUsehook - merges
Stophook - installs skill to
~/.claude/skills/brainrot/
- appends Brainrot instructions to
~/.gemini/GEMINI.md
- appends Brainrot instructions to
~/.codex/AGENTS.md
Copies the runtime to:
~/.brainrot/
daemon.mjs
browser-feed.html
hooks/
profiles/
config.json
curl -fsSL https://raw.githubusercontent.com/deepmroot/brainrot/main/install.sh | bashirm https://raw.githubusercontent.com/deepmroot/brainrot/main/install.ps1 | iexnpx -y github:deepmroot/brainrotnpm install -g github:deepmroot/brainrot
brainrotIf you use pi and want the simplest skill-style setup:
mkdir -p ~/.pi/agent/skills/brainrot
cp agents/brainrot.md ~/.pi/agent/skills/brainrot/SKILL.md
node bin/install.jsThis keeps the install similar to other skill-based setups.
It gives pi a Brainrot skill plus the shared runtime in ~/.brainrot/.
Note: this repo does not yet auto-wire a pi-native extension. The pi path here is a manual skill install.
node bin/install.js- Node.js 18+
- One supported coding agent:
- Claude Code
- Gemini CLI
- Codex
- Edge, Chrome, or Chromium
Per-agent install behavior
- merges
PreToolUseinto~/.claude/settings.json - merges
Stopinto~/.claude/settings.json - installs the Claude skill to
~/.claude/skills/brainrot/
- appends Brainrot instructions to
~/.gemini/GEMINI.md
- appends Brainrot instructions to
~/.codex/AGENTS.md
- copy
agents/brainrot.mdto~/.pi/agent/skills/brainrot/SKILL.md - run
node bin/install.jsto place the shared runtime in~/.brainrot/ - manual install only for now; no bundled pi-native extension wiring yet
Run:
/brainrot
Then:
- pick a provider
- if needed, log in once in the browser window
- finish setup
- Brainrot is armed for later runs
Run:
/brainrot
This does not open the feed immediately after setup is complete. It arms Brainrot for the next coding run.
When the agent starts working, Brainrot opens automatically. When the run ends, the browser is hidden and your work window is refocused.
/brainrot menu
Use this when you want to:
- launch immediately
- switch provider
- toggle autoscroll
- open an overlay demo
- turn Brainrot off
/brainrot
/brainrot menu
/brainrot status
/brainrot on
/brainrot off
/brainrot provider tiktok
/brainrot provider instagram
/brainrot provider youtube-shorts
/brainrot provider x
/brainrot provider local
/brainrot provider-ready current
/brainrot provider-reset current
/brainrot mode browser
/brainrot mode overlay
/brainrot mode both
/brainrot position center
/brainrot position left
/brainrot position right
/brainrot autoscroll on
/brainrot autoscroll off
/brainrot browser-url https://example.com/
/brainrot browser-url local
/brainrot demo browser
/brainrot demo overlay
/brainrot demo both
| Provider | Login required | Persistent profile | Notes |
|---|---|---|---|
local |
no | yes | built-in fake feed preview |
tiktok |
yes | yes | real feed after one-time login |
instagram |
yes | yes | real feed after one-time login |
youtube-shorts |
yes | yes | includes autoplay kickstart logic |
x |
yes | yes | real feed after one-time login |
You can override the built-in provider target with a custom URL:
/brainrot browser-url https://www.tiktok.com/
Clear the override and return to the selected provider:
/brainrot browser-url local
Brainrot uses three main runtime states:
| State | Meaning |
|---|---|
armed |
ready for the next coding run |
live |
browser/feed is currently active |
setup |
provider login or first-time setup still pending |
The status footer reflects this in the agent UI.
This is one of the main behaviors of the project.
When the agent finishes:
- Brainrot hides the browser window instead of always killing it
- the underlying provider session stays alive when possible
- the next time the same provider/profile is opened, the same live session is restored
This means a short, reel, or feed can continue from the same running session rather than being relaunched from scratch.
Autoscroll is designed for real provider pages when the user is idle.
- enabled by default
- waits for an idle window before acting
- does not run during initial login/setup
- intended mainly for live provider feeds, not the local fake feed
/brainrot autoscroll on
/brainrot autoscroll off
YouTube Shorts can open in a paused state on first display depending on browser autoplay restrictions.
Brainrot includes a playback kickstart step for Shorts that:
- finds the active video
- simulates a player interaction
- calls
video.play() - retries shortly after open when needed
~/.brainrot/
daemon.mjs local runtime daemon
browser-feed.html local fake feed
config.json persisted state
profiles/ per-provider or per-site browser profiles
hooks/
start.sh
stop.sh
activate-visual.sh
deactivate-visual.sh
- Agent starts working
start.shruns- daemon opens or restores the matching browser session
- agent finishes
stop.shruns- browser is hidden or stopped depending on state
- work window is refocused
For a full checklist, see:
Short version:
/brainrot
/brainrot status
/brainrot demo browser
/brainrot menu
/brainrot autoscroll off
/brainrot provider youtube-shorts
Release checklist
- verify install paths still work:
install.shinstall.ps1node bin/install.jsnpx -y github:deepmroot/brainrot
- run smoke tests from
TESTING.md - confirm README screenshots and GIF still match behavior
- commit changes
- tag a release
- push branch and tags
- publish release notes on GitHub
Example:
git add .
git commit -m "Release v1.1.0"
git tag v1.1.0
git push origin main --tagsPotential follow-up work:
- stronger provider-specific autoplay recovery
- smarter login completion detection
- richer local fake feed statistics
- more window-placement controls
- additional supported coding agents
MIT