← All projects

Two ways to read this page

• Understand the system: The spark → The struggle → The decisions → How it works → Where it stands → Reflection.
• Build your own: Constraints → Architecture → The gate rule → The experiment pattern → Exercises at the end.

“Automate everything except the judgment.”

The project began with the cheapest observation in the creator economy: consistency beats genius, and consistency is exactly what humans fail at. Upload schedules slip, metadata gets sloppy, analytics go unread. An agent doesn’t get tired — but an unsupervised agent publishes garbage at machine speed. So this one was built backwards from the publish button: what must be true before anything goes public? Quality gates, rights checks, human review — then automate everything upstream of them.

The spark

Every YouTube automation tool demoed the same trick: generate a video, upload it, walk away. The videos were unwatchable and the channels died within weeks — not for lack of automation, but for lack of taste enforced by process. Research without angles, scripts without retention structure, thumbnails without testing, publishing without review. Each stage is easy to automate badly and hard to automate well.

So AgentTube splits the channel into seven specialist agents — strategy, script, thumbnail, SEO, production, publishing, analytics — each owning one stage with its own inputs, checks, and outputs. Specialists can be judged; a monolith can only be trusted. And nothing schedules until quality, rights, and human-review gates pass by default.

The struggle

Three things went wrong enough to leave marks. All three are in the repo history, which is the point.

Narration repairs broke timing. Regenerated narration kept the old scene duration, so rebuilt videos played correct words over stale timing — long silent gaps where scenes used to be. The fix: repairs recompute duration from the replacement audio. The September 2026 hotfixes record it. Silence is data too: a gap means the timing model lied.

The pipeline forced one visual style. Scene generation and repair prompts hardcoded the ethereal look even when the channel configured another direction. The fix: prompts read the channel’s visual direction instead of assuming one. Aesthetic defaults are decisions wearing camouflage — this one got caught.

External tools failed the whole run. The DarkzSEO audit, Python checkouts, and narration providers each had failure modes that killed productions outright (No module named darkzseo, missing runtimes, broken configs). The fix is a boundary rule: bundled advisory audits are the default, external runtimes are JSON-only stdin/stdout with no shell and no inherited secrets, and anything missing falls back instead of failing. v2.10.0 made that boundary explicit.

And one honest admission: internal CTA metadata and bracketed placeholders kept leaking into spoken narration — stage directions read aloud as dialogue. The fix excludes them, including mid-line placeholders. The embarrassment this prevents is left to the imagination.

The decisions

Neither table is universal advice. Each row holds only under this project’s constraints: one operator, reputation as the scarcest resource, open-source self-hosting. Change the constraints and the answers change — that is what makes them decisions rather than preferences.

How it works

• Node.js 18+
• Express
• SQLite
• googleapis + OAuth loopback
• FFmpeg
• Playwright
• Winston
• node-cron

The whole system is one pipeline — research, script, narrate, assemble, optimize, review, schedule, publish, learn — drawn below as a video travels it. Six terms, explained once and never again:

• Specialist agents. Seven scripts in agents/, each owning a stage. Strategy turns objectives into content plans; script writes with retention structure; thumbnail designs; SEO optimizes metadata; production assembles; publishing schedules; analytics reads the results back into the next cycle.
• Approval gates. Simulated video, missing narration, unresolved claims, unconfirmed rights — each blocks scheduling until resolved, then a human still reviews in Review Studio.
• Evidence store. SQLite holds audits (rule IDs, severities, fingerprints), decisions with reasons, experiment arms and intervals, activation milestones.
• Growth experiments. Controlled title/thumbnail rotations with measured intervals and restored controls — no permanent change without a separate adoption decision.
• Scheduler. node-cron daily automation plus Review Studio controls (reschedule, publish now, delete schedule without deleting content).
• Provider flexibility. Gemini, OpenAI, OpenRouter, Kimi, and OpenAI-compatible endpoints for text; Seedance, MiniMax, Kling, Wan, or local FFmpeg for video. No vendor lock, no single bill.

flowchart TB
  R["Research topic + angle"]
  S["Script with retention structure"]
  N["Narration + visuals"]
  A["Assemble + metadata"]
  G{"Gates pass?"}
  H["Human review"]
  P["Schedule + publish"]
  L["Analytics back into strategy"]
  R --> S --> N --> A --> G
  G -->|no| F["Fix, re-enter"]
  F --> S
  G -->|yes| H --> P --> L

flowchart LR
  C["Control: current packaging"]
  V["Variant: approved arm only"]
  M["Measure real interval"]
  D{"Adopt?"}
  R["Restore control first"]
  C --> V --> M --> D
  D -->|yes, separate decision| A["Adopt winner"]
  D -->|no| R

Three chains connect requirements to what got built:

Reputation must survive automation → gates before scheduling, humans before publishing. Every past embarrassment is a standing rule; Review Studio keeps the human fast rather than bypassed.

Growth must be evidence, not folklore → SQLite records with stable IDs. Dismissals carry reasons, experiments carry controls, outcomes carry intervals. The database remembers what the dashboard forgets.

Vendors must stay interchangeable → open endpoints everywhere. Text, video, and narration each accept multiple providers behind the same interfaces. The channel cannot be held hostage by one bill.

The contract, then the code

The dashboard and the agents agree on jobs before either runs them. The daily driver is the scheduler plus standalone agent runs, all real from package.json:

# Daily channel operation: research → produce → review → schedule
npm run scheduler

# Run one specialist alone (each stage demoable in isolation)
npm run agent:strategy
npm run agent:script
npm run agent:seo

# Health check: 46-test system suite (gates included)
npm test

Broken promises get honest behavior: missing runtimes fall back to bundled audits instead of failing; missing strategy context no longer crashes generation (null-safe); OAuth normalizes legacy callback settings instead of stranding authorization. The shape never changes; only the data does.

Follow one video end to end (names real): the strategy agent turns the objective into a content plan, script-writer drafts with retention structure, narration generates (repaired timing included), production assembles with FFmpeg, SEO optimizes metadata, the DarkzSEO preflight audits discoverability, gates check quality/rights/claims, Review Studio schedules, publishing uploads with correct metadata, and analytics feeds interval evidence back into strategy. Each handoff is a file, a row, or a job — never a hope.

Who remembers what: SQLite holds audits, decisions, experiments, and activation milestones (back it up). The projects/, schedules/, and reports/ directories hold working state in the open. Credentials stay local and self-hosted — that is the whole pitch: your channel data never leaves your machine.

Where it stands

Running it costs the machine plus provider calls per generation — scheduling, review, and evidence are all local and free. That shape is designed, not lucky: the expensive generation happens per video, everything else runs on SQLite and cron. Self-hosting keeps credentials, media, and channel data under one roof — which is also why there is no hosted bill to report.

How AI was actually used here

The agents ARE the AI use, and the loop around them is not: models draft strategies, scripts, thumbnails, and metadata; gates, tests, SQLite, and humans judge. What gets delegated: research, drafting, assembly, measurement. What doesn’t: the publish decision, rights confirmation, experiment adoption.

Verification is mechanical, not hopeful: the 46-test suite covers gates and hotfix paths; Review Studio makes the human the last check, not the first victim; experiments need controls before claims.

flowchart TB
  S["Objective + guardrails"]
  S --> C["Crew produces"]
  C --> G["Gates check"]
  G -->|fail| F["Fix upstream"]
  F --> C
  G -->|pass| H["Human reviews"]
  H --> P["Publish + measure"]
  P --> E["Evidence recorded"]
  E --> S

One gap I’ll name plainly: the whole loop assumes the operator reviews well — tired reviewers rubber-stamp, and no gate in the repo measures review quality itself. Growth experiments guard the packaging; nothing guards the guardian.

Reflection

What worked. Specialists over monolith — failures arrive with stage names attached. Approval-first as default rather than aspiration. The bundled-fallback boundary (v2.10.0) turning missing tools into degraded modes instead of dead runs.

What didn’t. Narration timing drift (fixed via repair recompute). Forced visual styles (fixed via channel direction). Bracketed placeholders spoken aloud (fixed via exclusion). Each was a default masquerading as a decision.

What surprised me. How much of “automation” turned out to be review tooling — Review Studio, experiments, ROI alignment. The generating is easy; the trusting is the product.

What I’d change. Measure review quality (the unguarded guardian). Collapse the seven handoff formats into fewer, stricter contracts. Version the prompts alongside the code they drive.

What remains unsolved. Whether controlled experiments actually lift packaging performance in the wild — the machinery is built, the intervals are honest, but the wins are still ahead. That experiment is scoped and waiting: run arms, restore controls, publish numbers.

Build your own

Reproduce it exactly (npm install, npm run walkthrough, npm start — the walkthrough is your checkpoint), then: run one specialist alone and read what it produces before judging the pipeline; break one gate on purpose and confirm nothing schedules; rotate one title arm in Growth Experiments and restore the control; point the strategy agent at your own niche and argue with its content plan — write down where it’s wrong, that becomes the project’s next prompt improvement.

Five things worth keeping: specialists beat monoliths for blame. Gates encode past embarrassments as rules. Bundled defaults with graceful fallbacks beat hard dependencies. Experiments need controls and second decisions. Automate everything except the judgment.

Go deeper

The closest sibling is the Autonomous Data Engineer — same philosophy (machine proposes, human disposes, database remembers), different domain (data jobs, not videos). Read them as a pair: one gates pipelines, the other gates publishing. For the failure stories both philosophies produce, the part-1 system story shows what happens when the machine trusts too much — and the Mastery platform shows the opposite bet: no agent at all.