YouTube Automation Agent - ECGHuNZSECqTXabaLjkVrTEnguiNZLkKF1qi8oBGpump

The open-source AI agent that runs a YouTube channel end to end.

Research topics → write scripts → generate narration and visuals → assemble videos → optimize metadata → review → schedule → publish → learn from analytics.

Self-hosted: your credentials, media, and channel data stay under your control.
Approval-first: nothing is scheduled until quality, rights, and human-review gates pass by default.
Provider-flexible: use Gemini, OpenAI, OpenRouter, Kimi, MiMo, GLM, or another OpenAI-compatible endpoint.
Observable: follow persistent generation jobs, failures, review state, publishing, and local activation milestones from the dashboard.

Quick start

git clone https://github.com/darkzOGx/youtube-automation-agent.git
cd youtube-automation-agent
npm install
npm run walkthrough
npm start

Open http://localhost:3456. The walkthrough explains each provider choice, tests credentials, and guides YouTube authorization.

Already know what you are doing? npm run setup offers a shorter classic flow, and .env.example documents every setting.

What you need

Node.js 18+
A Google account and YouTube Data API credentials
At least one AI text provider key
FFmpeg, installed automatically through ffmpeg-static

Gemini offers free access for supported text and TTS usage. Gemini AI image generation currently requires paid-tier access; without an image provider, Lumen can assemble gradient-based visuals instead.

From idea to published video

Stage	What Lumen 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 in Review Studio	Facts, media rights, edits, approval
Publish	Schedules and uploads approved content	Privacy, timing, final decision
Learn	Pulls performance signals into the next strategy cycle	Automation and optimization settings

Lumen distinguishes real MP4 output from simulated placeholders. Simulated output cannot enter the approval or publishing path.

For release history, see CHANGELOG.md.

Architecture

graph TD
    A[Content Strategy Agent] --> B[Script Writer Agent]
    B --> C[Thumbnail Designer Agent]
    B --> D[SEO Optimizer Agent]
    C --> E[Production Management Agent]
    D --> E
    E --> F[Publishing & Scheduling Agent]
    F --> G[Analytics & Optimization Agent]
    G -->|feedback loop| A

How It Works

Each agent handles one stage of the pipeline:

Agent	Role
Content Strategy	Analyzes YouTube trends, identifies topics, plans content calendar
Script Writer	Generates scripts with hooks, storytelling, CTAs
Thumbnail Designer	Creates thumbnails, runs A/B variations
SEO Optimizer	Keywords, titles, descriptions, tags
Production	Coordinates TTS audio, image assets, video assembly
Publishing	Uploads, schedules, manages playlists
Analytics	Tracks performance, feeds insights back to strategy

AI Providers

All OpenAI-compatible providers work out of the box — the system auto-configures the SDK base URL. Pick one, or use OpenRouter to access everything through a single key.

graph LR
    subgraph Direct
        OA[OpenAI<br/>GPT-5.6 family]
        GM[Gemini<br/>3.7 Flash / 3.1 Pro]
        KM[Kimi<br/>K3]
        MM[MiMo<br/>V2.5 Pro]
        GL[GLM<br/>GLM-5.3]
    end
    subgraph Router
        OR[OpenRouter<br/>400+ models]
    end
    Direct --> YAA[YouTube Automation Agent]
    Router --> YAA

Provider	Models	Base URL	Cost
OpenAI	GPT-5.6 Sol, Terra, Luna	`api.openai.com/v1`	provider pricing
OpenRouter	400+ models; curated defaults are validated against its live catalog	`openrouter.ai/api/v1`	varies by model
Google Gemini	Gemini 3.7 Flash, 3.1 Pro Preview, 3.5 Flash-Lite	via `@google/genai` SDK	free tiers vary by model and modality
Kimi (Moonshot AI)	Kimi K3, K2.7 Code, K2.6	`api.moonshot.ai/v1`	provider pricing
MiMo (Xiaomi)	MiMo V2.5 Pro, V2.5	`api.xiaomimimo.com/v1`	provider pricing
GLM (Zhipu AI)	GLM-5.3, 5.2, 5.1	`api.z.ai/api/paas/v4/`	provider pricing

Additional integrations: Anthropic Claude (claude-fable-5), ElevenLabs (Eleven v3 TTS), Replicate (Wan 2.7 video), local models via Ollama, any OpenAI-compatible endpoint.

Configuration

API Keys

YouTube Data API (required, free)

Create a project in Google Cloud Console
Enable YouTube Data API v3
Create an OAuth 2.0 client (Desktop app)
Save the JSON as config/credentials.json

OpenAI

Get a key from platform.openai.com
Set OPENAI_API_KEY in .env

OpenRouter (easiest — one key, all models)

Get a key from openrouter.ai/keys
Set OPENROUTER_API_KEY in .env

Google Gemini

Get a key from Google AI Studio
Set GEMINI_API_KEY in .env

Kimi / MiMo / GLM

Provider	Get key at	Env var
Kimi (Moonshot AI)	platform.kimi.ai	`MOONSHOT_API_KEY`
MiMo (Xiaomi)	mimo.mi.com	`MIMO_API_KEY`
GLM (Zhipu AI)	z.ai	`GLM_API_KEY`

Environment Variables

# AI provider — pick one (or use OpenRouter for access to all)
OPENAI_API_KEY=sk-...
# OPENROUTER_API_KEY=sk-or-...
# GEMINI_API_KEY=...
# MOONSHOT_API_KEY=...
# MIMO_API_KEY=...
# GLM_API_KEY=...

# Optional: premium TTS
# ELEVENLABS_API_KEY=...
# ELEVENLABS_VOICE_ID=...

# Optional: AI video generation
# REPLICATE_API_KEY=...

# App config
NODE_ENV=production
PORT=3456
CHANNEL_NAME=Your Channel Name
TARGET_AUDIENCE=Your target audience
YOUTUBE_REGION=US
DEFAULT_PRIVACY_STATUS=private

# Optional: protect mutating API routes (POST /generate, /publish)
# API_KEY=some-long-random-string

# Optional anonymous activation milestones (off by default; HTTPS endpoint required)
# ANONYMOUS_TELEMETRY_ENABLED=false
# ANONYMOUS_TELEMETRY_ENDPOINT=https://your-collector.example/events

Activation measurement and privacy

The dashboard calculates setup, first-real-MP4, approval, publication, and repeat-generation milestones locally from SQLite and files on disk. A video counts only when a non-simulated .mp4 with an MP4 container signature still exists.

Anonymous milestone reporting is disabled by default and has no built-in collector. It activates only when you explicitly set both telemetry variables. The allowlisted payload contains the milestone name and time, Lumen version, OS family, Node major version, and a random installation ID. It never includes credentials, channel data, prompts, topics, titles, filenames, or video contents.

Automation Schedule

gantt
    title Daily Pipeline
    dateFormat HH:mm
    axisFormat %H:%M

    section Content
    Generate content (strategy + script + thumbnail + SEO) :06:00, 2h

    section Publishing
    Process publishing queue :crit, 08:00, 14h

    section Analytics
    Collect analytics     :09:00, 1h
    Run optimizations     :22:00, 1h

The scheduler runs automatically after npm start. Content generation at 06:00, publishing queue processed every 15 minutes, analytics at 09:00, optimization at 22:00. Weekly strategy reviews run on Sundays.

API

# health check
curl http://localhost:3456/health

# queue a video-generation job (send x-api-key if API_KEY is set in .env)
curl -X POST http://localhost:3456/generate \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{"topic": "Top 10 Life Hacks", "style": "list"}'

# inspect the returned background job
curl http://localhost:3456/api/jobs/:jobId

# view schedule
curl http://localhost:3456/schedule

# get analytics
curl http://localhost:3456/analytics

# inspect, edit, and approve content before scheduling
curl http://localhost:3456/api/content/:contentId
curl -X POST http://localhost:3456/api/content/:contentId/approve \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{"privacyStatus":"private","factChecked":true,"rightsConfirmed":true}'

Production Pipeline

flowchart LR
    subgraph TTS["Audio Generation"]
        direction TB
        EL[ElevenLabs v3] -.->|fallback| OA[OpenAI TTS]
        OA -.->|fallback| SIM1[Simulation]
    end

    subgraph IMG["Image Generation"]
        direction TB
        GPT[GPT Image 2] -.->|fallback| SIM2[Simulation]
    end

    subgraph VID["Video Assembly"]
        direction TB
        WAN[Wan 2.7 I2V] -.->|fallback| PW[Playwright Slideshow]
        PW -.->|fallback| SIM3[Simulation]
    end

    TTS --> MIX[FFmpeg Mux]
    IMG --> VID
    VID --> MIX
    MIX --> OUT[Final Video]

Each stage has graceful fallbacks. If a paid API key isn't configured, the system simulates that step so the rest of the pipeline still runs.

Extending

Custom AI provider

// utils/ai-service.js
const Anthropic = require('@anthropic-ai/sdk');

class ClaudeAIService {
  constructor(apiKey) {
    this.client = new Anthropic({ apiKey });
  }
  async generateContent(prompt) {
    const message = await this.client.messages.create({
      model: 'claude-fable-5',
      max_tokens: 1024,
      messages: [{ role: 'user', content: prompt }]
    });
    return message.content[0].text;
  }
}

Custom content types

// agents/content-strategy-agent.js
const contentTypes = {
  'podcast': {
    duration: '10-15 minutes',
    style: 'conversational',
    thumbnail: 'podcast-style'
  },
};

Project Structure

youtube-automation-agent/
├── agents/          # one file per agent
├── config/          # credentials, example configs
├── database/        # SQLite schema and access layer
├── data/            # generated content and assets
├── schedules/       # cron-based automation
├── utils/           # AI service wrappers, logging, credential management
├── .github/         # CI workflow (lint + tests on every push/PR)
└── index.js         # Express server + agent initialization

Troubleshooting

Problem	Fix
`Missing credentials for: an AI provider`	Configure any one provider with `npm run credentials:setup` — OpenAI is not required
`'ffmpeg' is not recognized` / no .mp4 produced	Run `npm install` (fetches the bundled binary), or install FFmpeg and set `FFMPEG_PATH`
Video marked `simulated`, nothing uploads	Check the ✗ lines in the startup capability check — a key or FFmpeg is missing
"Processing publish queue" but nothing publishes	The queue log now shows what's waiting; content publishes at its scheduled time (default: next day 2 PM)
YouTube API quota exceeded	Check quotas in Google Cloud Console; reduce posting frequency
Content generation failed	Verify API keys and credits; check `logs/`
Publishing failed	Re-authenticate YouTube OAuth tokens; check video format

Enable debug logging:

NODE_ENV=development DEBUG_MODE=true npm start

More Tools by darkzOGx

If this was useful, check out:

darkzloop: terminal agent runner that turns any LLM into a disciplined software engineer (FSM control, model-agnostic, BYO auth)
darkzBOX: open-source Instantly.ai clone with smart automated email replies
open-sales-researcher: autonomous B2B company research. Works with Claude Code, Cursor, Copilot.
darkzseo: SEO tooling

Built by

@darkzOGx, a solo builder shipping AI automation and developer tools. Find me on X and laderalabs.io.

If Lumen saves you time, a star helps it reach more developers.

Contributing

See CONTRIBUTING.md for ground rules (short version: one focused concern per PR, no lockfile churn, lint + tests must pass). For questions and setup help, use Discussions — Issues is for bugs.

Fork the repo
Create a feature branch
Make changes and add tests
Submit a PR

git clone <your-fork>
cd youtube-automation-agent
npm install
npm run lint   # must pass — CI runs this on every PR
npm test

License

MIT — see LICENSE.

Acknowledgments

OpenAI — GPT-5.6 Sol, GPT Image 2, GPT-4o-mini-tts
OpenRouter — unified multi-model API
Google — Gemini 3.7 Flash, Gemini 3.1 Flash Image, Gemini 3.1 Flash TTS
Google Cloud — YouTube Data API
Moonshot AI — Kimi K3
Xiaomi — MiMo V2.5 Pro
Zhipu AI — GLM-5.3
ElevenLabs — Eleven v3 TTS
Replicate — Wan 2.7 video generation
ConstructionBids.ai - AI scans every federal, state & local public works bid and matches you to contracts you'll win.

This tool is for legitimate content creation. Comply with YouTube's Terms of Service and Community Guidelines.

Name		Name	Last commit message	Last commit date
.github		.github
agents		agents
assets		assets
config		config
dashboard		dashboard
database		database
examples		examples
mcp		mcp
reports/growth		reports/growth
schedules		schedules
scripts/growth		scripts/growth
utils		utils
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
index.js		index.js
modern-auth.js		modern-auth.js
oauth-server.js		oauth-server.js
package-lock.json		package-lock.json
package.json		package.json
setup.js		setup.js
test.js		test.js
walkthrough.js		walkthrough.js

Navigation Menu

Repository files navigation

YouTube Automation Agent - ECGHuNZSECqTXabaLjkVrTEnguiNZLkKF1qi8oBGpump

Quick start

What you need

From idea to published video

Architecture

How It Works

AI Providers

Configuration

API Keys

YouTube Data API (required, free)

OpenAI

OpenRouter (easiest — one key, all models)

Google Gemini

Kimi / MiMo / GLM

Environment Variables

Activation measurement and privacy

Automation Schedule

API

Production Pipeline

Extending

Custom AI provider

Custom content types

Project Structure

Troubleshooting

More Tools by darkzOGx

Built by

Contributing

License

Acknowledgments

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

YouTube Automation Agent - ECGHuNZSECqTXabaLjkVrTEnguiNZLkKF1qi8oBGpump

Quick start

What you need

From idea to published video

Architecture

How It Works

AI Providers

Configuration

API Keys

YouTube Data API (required, free)

OpenAI

OpenRouter (easiest — one key, all models)

Google Gemini

Kimi / MiMo / GLM

Environment Variables

Activation measurement and privacy

Automation Schedule

API

Production Pipeline

Extending

Custom AI provider

Custom content types

Project Structure

Troubleshooting

More Tools by darkzOGx

Built by

Contributing

License

Acknowledgments

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages