Skip to content

🎬 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.

4.1 KB
Raw Blame

Contributing

Thanks for contributing! This project moves fast and PRs are reviewed regularly β€” a few ground rules keep that possible.

Ground rules

  1. 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.
  2. Don't regenerate package-lock.json unless your PR is specifically about dependencies. Lockfile churn hides real changes and is a supply-chain review burden.
  3. Lint and tests must pass β€” CI runs npm run lint and npm test on every PR. If you fix a bug, add a regression test in test.js (see the existing SystemTest methods for the pattern).
  4. Rebase on master before opening or updating a PR.
  5. Describe how you tested it. "Ran npm start, generated a video with Gemini-only credentials, verified a real .mp4 appeared in data/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.