π¬ Open-source, self-hosted AI agent that runs a YouTube channel end to end: researches topics, writes scripts, generates narration, visuals and video, optimizes SEO, and publishes after your approval, then learns from analytics. Works with Gemini, OpenAI, OpenRouter, DeepSeek and more.
Contributing
Thanks for contributing! This project moves fast and PRs are reviewed regularly β a few ground rules keep that possible.
Ground rules
- One concern per PR. A focused 50-line PR merges in days; a 6,000-line PR mixing features can't be responsibly reviewed. If your change has independent parts, stack them as separate PRs.
- Don't regenerate
package-lock.jsonunless your PR is specifically about dependencies. Lockfile churn hides real changes and is a supply-chain review burden. - Lint and tests must pass β CI runs
npm run lintandnpm teston every PR. If you fix a bug, add a regression test intest.js(see the existingSystemTestmethods for the pattern). - Rebase on
masterbefore opening or updating a PR. - Describe how you tested it. "Ran
npm start, generated a video with Gemini-only credentials, verified a real .mp4 appeared indata/videos/" beats any amount of code description.
Getting started
git clone <your-fork>
cd youtube-automation-agent
npm install # also fetches the bundled FFmpeg binary
npm test # 12 system tests, no credentials needed
npm run lint
You don't need API keys to work on most of the codebase β the test suite and the simulation fallbacks run without them. For end-to-end runs, npm run setup walks you through credentials (any one AI provider is enough).
Project structure
youtube-automation-agent/
βββ agents/ # one file per pipeline agent (strategy, script, thumbnail, SEO, production, publishing, analytics)
βββ dashboard/ # web dashboard served by index.js
βββ database/ # SQLite schema and access layer
βββ schedules/ # cron-based automation
βββ scripts/ # maintenance scripts (growth snapshot, README screenshots)
βββ utils/ # AI text, media, and video providers; operator, readiness, engagement, and other services
βββ config/ # credential files (examples are committed)
βββ data/ # generated content and the local database
βββ docs/ # feature guide, API reference, providers, troubleshooting, design notes
βββ examples/ # verified real output from the community
βββ index.js # Express server and agent startup
βββ walkthrough.js # guided setup (npm run walkthrough)
βββ setup.js # classic setup (npm run setup)
βββ test.js # system test suite (npm test)
Extending
Add a text provider
Any provider with an OpenAI-compatible chat completions API can be added as a preset in utils/ai-text-service.js:
deepseek: {
name: 'DeepSeek',
baseURL: 'https://api.deepseek.com',
defaultModel: 'deepseek-flash',
models: ['deepseek-flash', 'deepseek-v4-pro'],
envKey: 'DEEPSEEK_API_KEY',
},
Then add a matching entry to AI_PROVIDER_GUIDE in walkthrough.js and a setup option in utils/credential-manager.js, add the provider to docs/providers.md, and run npm test. The walkthrough test fails if any provider is missing a complete guide.
Add a video provider
Video providers live in utils/video-providers.js. Each one extends VideoProvider, implements isAvailable, createTask, getTask, and downloadResult, and is registered in VideoProviderRegistry.
README screenshots
The screenshots in the README are captured by npm run docs:screenshots, which starts the dashboard from your checkout and saves PNGs to assets/screenshots/. Re-run it after a visible dashboard change. Capture from a database with at least one real production: the project never presents mock or simulated output as real.
Where help is most wanted
Check the open issues and the roadmap in the latest release notes. Current priorities: Gemini image/TTS parity, slideshow rendering performance, and template-content quality.
Reporting bugs
Use the bug report template β it asks for the startup capability check (π Capability check: block), which diagnoses most issues instantly.