YouTube Automation Agent
The open-source AI agent that runs a YouTube channel end to end, with you approving every video before it goes out.
It researches topics, writes scripts, generates narration and visuals, assembles real MP4s, writes titles, descriptions and tags, schedules approved videos, and learns from analytics and from what your audience says. It runs on your own machine with your own API keys.
| |
|---|
| Content review: quality checks and approval for one video | Autonomous operator: your mandate and the agent's plan |
Screenshots use sample data so every panel is populated. Regenerate them with npm run docs:screenshots.
Why it's different
- You approve before anything is published. Finished videos wait for fact review, media-rights confirmation, and your approval. Turning on autonomy doesn't skip those checks.
- Real output only. Simulated or placeholder media is clearly marked and can never be approved or uploaded.
- Self-hosted. Your keys, media, and channel data stay on your machine.
- Learns from evidence, with your sign-off. Lessons from analytics, retention curves, and comments shape future videos only after you approve them.
- Your choice of providers. Eight text providers or OpenRouter, five AI video providers, or free local slideshow rendering.
Quick start
You need:
- Node.js 18.17 or newer
- A Google account and YouTube Data API credentials (setup steps)
- An API key for at least one text provider. Gemini has free tiers for text and narration.
git clone https://github.com/darkzOGx/youtube-automation-agent.git
cd youtube-automation-agent
npm install
npx playwright install chromium # renders slideshow videos; on Linux add --with-deps
npm run walkthrough
npm start
Then open http://localhost:3456.
npm run walkthrough explains each provider choice, tests your keys, and connects your YouTube channel. For a shorter flow, use npm run setup. Every setting is documented in .env.example.- Check readiness. In the dashboard, open Production readiness and choose Run verified check. It makes small live text and narration requests, checks access to your channel, and builds and decodes a test MP4, without uploading anything.
- Make videos. Open Autonomous operator, describe the channel you want, and choose Activate & run now, or create a single video from the dashboard. Finished videos wait in Pipeline for your review and approval.
FFmpeg is installed with npm install through ffmpeg-static.
YouTube credentials
- Create a project in Google Cloud Console.
- Enable YouTube Data API v3, and YouTube Analytics API for retention and outcome data.
- Create an OAuth 2.0 client of type Desktop app (not Web application) and save the JSON as
config/credentials.json.
- Under Google Auth Platform → Audience, add the Google account that owns your channel as a test user. Otherwise sign-in fails with
Error 403: access_denied. While the app is in Testing mode, Google expires the sign-in after 7 days.
How it works
| Stage | What the agent does | What you control |
|---|
| Research | Finds topics and builds a content strategy | Niche, audience, blocked topics |
| Script | Writes the hook, narrative, CTA, and metadata | Voice, format, length, brand direction |
| Production | Generates narration and visuals, then assembles a real MP4 | Provider choice and media fallbacks |
| Review | Runs quality checks and opens the video for review | Facts, media rights, edits, approval |
| Publish | Schedules and uploads approved content | Privacy, timing, final decision |
| Learn | Captures 24-hour and 7-day evidence, measures your chosen outcome, then proposes the next move | Choose the KPI and approve or reject each lesson |
Features
Each item links to its walkthrough in the feature guide.
Plan
- Autonomous Channel Operator: give it an objective, audience, content pillars, cadence, and limits. It researches trends and competitors, builds an evidence-labeled plan, and sends each video through production.
- Outcome & ROI Studio: set a target (views, watch hours, net subscribers, engagement, or revenue) and a budget, and track progress. Missing data shows as unavailable, never as zero.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
