{"id":45544336,"url":"https://github.com/ghjj123/brainrotguard","last_synced_at":"2026-03-18T02:12:49.545Z","repository":{"id":338891270,"uuid":"1158733207","full_name":"GHJJ123/brainrotguard","owner":"GHJJ123","description":"YouTube approval system for kids — parent approves via Telegram, kid watches via web UI","archived":false,"fork":false,"pushed_at":"2026-02-23T02:58:18.000Z","size":62994,"stargazers_count":207,"open_issues_count":5,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-23T09:39:47.509Z","etag":null,"topics":["docker","fastapi","parental-controls","python","self-hosted","telegram-bot","youtube","yt-dlp"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GHJJ123.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-15T20:44:41.000Z","updated_at":"2026-02-23T09:18:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"76a3cddc-9aa9-4044-98e6-4544a9d3dac8","html_url":"https://github.com/GHJJ123/brainrotguard","commit_stats":null,"previous_names":["ghjj123/brainrotguard"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/GHJJ123/brainrotguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GHJJ123%2Fbrainrotguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GHJJ123%2Fbrainrotguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GHJJ123%2Fbrainrotguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GHJJ123%2Fbrainrotguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GHJJ123","download_url":"https://codeload.github.com/GHJJ123/brainrotguard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GHJJ123%2Fbrainrotguard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29980769,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T16:35:47.903Z","status":"ssl_error","status_checked_at":"2026-03-01T16:35:44.899Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","fastapi","parental-controls","python","self-hosted","telegram-bot","youtube","yt-dlp"],"created_at":"2026-02-23T04:40:03.823Z","updated_at":"2026-03-18T02:12:49.533Z","avatar_url":"https://github.com/GHJJ123.png","language":"Python","funding_links":["https://ko-fi.com/coffee4jj"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"web/static/brg-logo.png\" alt=\"BrainRotGuard\" width=\"300\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eYouTube approval system for kids.\u003c/strong\u003e\u003cbr\u003e\n  Your child searches for videos on a tablet. You approve or deny from your phone via Telegram.\n\u003c/p\u003e\n\n---\n\n## Contents\n- [What Is This?](#what-is-this)\n- [Features](#features)\n- [Quick Start](#quick-start)\n- [What You'll Need](#what-youll-need)\n- [Documentation](#documentation)\n- [License](#license)\n\n## What Is This?\n\nBrainRotGuard puts you in control of what your kids watch on YouTube — without standing over their shoulder.\n\nYour child gets a simple web page on their tablet where they can search YouTube and request videos. Every request sends you a Telegram message with the video thumbnail, title, channel, and duration. You tap **Approve** or **Deny** right in the chat. If approved, the video starts playing on their tablet automatically.\n\nNo YouTube account needed. No ads. No algorithmic rabbit holes. No \"up next\" autoplay.\n\n### How It Works\n\n```\nKid's Tablet ----\u003e BrainRotGuard Server ----\u003e Router ----\u003e Telegram Cloud ----\u003e Parent's Phone\n                                                |\n                                          DNS (AdGuard/Pi-hole)\n                                          X  youtube.com (blocked)\n                                          OK youtube-nocookie.com (allowed)\n```\n\n1. Kid opens BrainRotGuard on their tablet and searches for a video\n2. They tap **Request** on the one they want to watch\n3. You get a Telegram notification with all the details\n4. You tap **Approve** or **Deny**\n5. Their screen updates automatically — approved videos play right away\n\n### Screenshots\n\nWorks on any screen size — desktop, tablet, and phone:\n\n\u003cimg src=\"docs/screenshots/screenshots-combined.png\" alt=\"BrainRotGuard on desktop, tablet, and phone — homepage, search, watch, and activity views\" width=\"900\"\u003e\n\n### Demo\n\nKid searches, requests a video, parent approves via Telegram, video plays:\n\nhttps://github.com/user-attachments/assets/e36eeb48-bb28-4edd-8d8e-10d2fd30d002\n\n### Why I Built This\n\n\u003cdetails\u003e\n\u003csummary\u003eThe short version: YouTube's algorithm was winning, and every parental control was either too strict or too loose.\u003c/summary\u003e\n\nI'm a father of a preteen son. I didn't want to block YouTube completely — YouTube is genuinely how I learn things myself, and I wanted my son to have that same ability to research topics, explore educational content, and develop the problem-solving habit of \"let me figure this out.\" That's a skill I want him to have.\n\nThe problem was his feed. It was overrun with gamers screaming into microphones and brainrot content. I'd tell him to change the channel every time I walked by and heard one of those obnoxious gaming videos. He'd switch, but YouTube's algorithm would pull him right back within minutes. The algorithm is designed to keep kids glued — and it's very good at its job.\n\nEvery parental control I tried was either too restrictive (block YouTube entirely) or too permissive (YouTube Kids still recommends garbage). I needed the middle ground: let him explore and search freely, but give me the final say on what actually plays.\n\nI'm not a developer — just a dad who wanted to protect his kid from YouTube's brainrot algorithms. I am a homelab enthusiast though, so I'm comfortable tinkering with self-hosted tools. I built this entirely with Claude (Anthropic's AI) — I described what I wanted, Claude wrote the code. Every release went through security reviews and code reviews via Claude before I pushed it.\n\nBrainRotGuard removes the algorithm entirely. There's no autoplay, no \"up next\" sidebar, no recommendation engine pulling him deeper. He searches for what he wants, I approve or deny, and the video plays and stops. Done. No rabbit holes.\n\nDon't want them watching gaming content? Block those channels. Tired of a specific creator? One tap. You can allow the channels you trust (educational, science, building, nature) and block the ones you don't — and it sticks. He picks what to ask for, I have the final say.\n\nNow I curate his content and I can see the difference. He's not parroting gamer lingo back at me anymore. The stuff he watches is actually interesting — things he's curious about, things he's learning from. I pair this with Google Family Link on his device for general screen time, but BrainRotGuard is what controls YouTube specifically: daily time limits, scheduled access windows, and per-channel approval. Family Link says \"the tablet turns off at 8pm.\" BrainRotGuard says \"you can watch 2 hours of entertainment YouTube today, but educational content is unlimited — and only from channels I've approved.\"\n\u003c/details\u003e\n\n## Features\n\n### For Kids\n- **Works on any device** — it's just a web page. Android tablet, iPad, laptop, phone, Kindle Fire — if it has a browser, it works\n- **Simple search** — type what you want, see results, tap Request\n- **Instant playback** — approved videos play immediately, no waiting\n- **Video library** — browse everything that's been approved before\n- **Category browsing** — filter by educational or entertainment content with one tap\n- **Channel browsing** — see latest videos from pre-approved channels without needing to request each one\n- **YouTube Shorts** — dedicated Shorts row with portrait thumbnails and a 9:16 player\n- **Thumbnail previews** — hover or scroll to cycle through multiple thumbnails before requesting\n- **Dark theme** — easy on the eyes, designed for tablets\n\n### For Parents\n- **Telegram approval** — approve/deny from anywhere with one tap\n- **Channel allow/block lists** — trust a channel once, and new videos from it are auto-approved\n- **Multi-child profiles** — separate PINs, watch history, and time budgets per child\n- **Edu/Fun categories** — label channels and videos as educational or entertainment, each with its own daily time limit\n- **Daily screen time limits** — set separate limits for educational and entertainment content, or a single global limit\n- **Scheduled hours** — define when watching is allowed (e.g., 8am–7pm, not during school)\n- **Per-day schedules** — different time windows and limits for each day of the week (e.g., relaxed weekends, tighter school days)\n- **Guided setup wizard** — `/time setup` walks through limit mode and schedule configuration with inline buttons\n- **Bonus time** — grant extra minutes for today only (`/time add 30`)\n- **Shorts control** — toggle YouTube Shorts visibility across the entire app\n- **Watch activity log** — see what was watched, for how long, grouped by category\n- **Localized UI and bot** — English and Norwegian support, with locale-aware or forced 12h/24h time display\n- **Word filters** — block videos whose titles contain specific words\n- **Search history** — see everything your child has searched for\n- **Starter channels** — curated list of kid-friendly channels (edu + fun) to import on first boot\n- **Update notifications** — automatic Telegram alert when a new version is available on GitHub\n- **PIN lock** — optional PIN gate so only your kid can access the web UI on the right device\n\n### Privacy \u0026 Security\n- **100% self-hosted** — runs entirely on your own hardware inside your home network. No cloud service, no third-party accounts, no subscriptions\n- **No YouTube account required** — no sign-in, no tracking, no personalized ads\n- **No API key needed** — uses [yt-dlp](https://github.com/yt-dlp/yt-dlp) for search and metadata\n- **Privacy-respecting embeds** — videos play via `youtube-nocookie.com` (Google's reduced-tracking embed domain)\n- **Single-file database** — all data is one SQLite file on your machine. Nothing phones home.\n- **Container runs as non-root** — Docker security best practice\n\n## Quick Start\n\n\u003e **Prerequisites:** [Docker](https://docs.docker.com/get-docker/), a [Telegram bot token](https://core.telegram.org/bots#how-do-i-create-a-bot), and your [chat ID](docs/setup.md#step-2-get-your-chat-id). New to this? The **[full setup guide](docs/setup.md)** walks through everything step by step.\n\n```bash\ngit clone https://github.com/GHJJ123/brainrotguard.git\ncd brainrotguard\ncp .env.example .env\ncp config.example.yaml config.yaml\n# Edit .env with your bot token and chat ID\ndocker compose up -d\n```\n\nOpen `http://\u003cyour-server-ip\u003e:8080` on the kid's tablet.\n\n**Pre-built image** (no build step, supports amd64 + arm64):\n```bash\ndocker pull ghcr.io/ghjj123/brainrotguard:latest\n```\nSee the [full setup guide](docs/setup.md#using-the-pre-built-docker-image) for compose file details.\n\n**Unraid:** Search for **BrainRotGuard** in Community Applications, or download the template manually:\n```bash\nwget -O /boot/config/plugins/dockerMan/templates-user/my-brainrotguard.xml \\\n  https://raw.githubusercontent.com/GHJJ123/brainrotguard/main/unraid-template.xml\n```\nSee the [full Unraid setup guide](docs/setup.md#installing-on-unraid) for details.\n\n**Important:** You'll also want to [block YouTube at the DNS level](docs/setup.md#step-5-block-youtube-on-the-kids-devices) on the kid's devices — otherwise they can just open youtube.com directly.\n\n## What You'll Need\n\n| Requirement | What It Is |\n|-------------|-----------|\n| **A computer that stays on** | Raspberry Pi, old laptop, or home server — anything running Docker |\n| **Docker** | [Install Docker](https://docs.docker.com/get-docker/) |\n| **Telegram account** | The messaging app where you'll receive approval requests |\n| **Telegram bot token** | Created in 5 minutes via [@BotFather](https://core.telegram.org/bots#how-do-i-create-a-bot) |\n| **DNS-level blocking** | [AdGuard Home](https://adguard.com/en/adguard-home/overview.html), [Pi-hole](https://pi-hole.net/), or router-level blocking |\n\n\u003e **Why Telegram?** It was the easiest way to build instant notifications with approve/deny buttons that work from your phone. No custom app to develop, no push notification infrastructure to maintain — Telegram handles all of that.\n\n\u003e **Network note:** BrainRotGuard runs on your home network. Your child's device needs to be on the same network (that's where DNS blocking and the web UI live). You can approve/deny from anywhere via Telegram — you don't need to be home for that part.\n\n## Documentation\n\n- **[Setup Guide](docs/setup.md)** — full walkthrough from Telegram bot creation to DNS blocking\n- [Configuration Reference](docs/configuration.md) — config.yaml options, environment variables, defaults\n- [Locale Guide](i18n/locales/README.md) — how translations work and how to add a new language\n- [Telegram Commands](docs/telegram-commands.md) — full command list for the parent bot\n- [Troubleshooting](docs/troubleshooting.md) — common issues and fixes\n- [Architecture](docs/architecture.md) — system diagrams and request flow\n- [Design Decisions](docs/design-decisions.md) — why yt-dlp, Telegram, SQLite, etc.\n- [Running Without Docker](docs/running-without-docker.md) — plain Python setup (no containers)\n\n## Support\n\nIf you find BrainRotGuard useful:\n\n[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/coffee4jj)\n\n## License\n\n[MIT](LICENSE) — use it however you want.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghjj123%2Fbrainrotguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fghjj123%2Fbrainrotguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghjj123%2Fbrainrotguard/lists"}