# pedromeloofficial/youtube-agent-matrix architecture

> Architecture diagram of the GitHub repository pedromeloofficial/youtube-agent-matrix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pedromeloofficial/youtube-agent-matrix
- Repository: https://github.com/pedromeloofficial/youtube-agent-matrix

## Overview

YouTube Agent Matrix is a Claude Code pre-production system: creators request work through the orchestrator, which routes to specialized agents and produces creator-facing plans and assets. Its documented full-video workflow moves through research, ideation and approval, SEO, scripting and approval, then recording-document generation and parallel thumbnail, metadata, and Shorts work. Other major branches cover channel strategy, audits, competitors, calendars, repurposing, monetization, and analytics. Optional execution scripts fetch YouTube data and transcripts or transcribe voice recordings. The README documents agent routing; source excerpts show execution-script internals, not how agents invoke them.

Main entry points: [`skills/orchestrator/SKILL.md`](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/skills/orchestrator/SKILL.md) (Orchestrator), [`agents/script-agent.md`](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/script-agent.md) (Script Agent), [`execution/search_competitor_videos.py`](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/search_competitor_videos.py) (Competitor Video Search), [`execution/fetch_channel_data.py`](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/fetch_channel_data.py) (Channel Data Fetch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coord["Orchestration"]
  node_orchestrator["Orchestrator<br/>[SKILL.md]"]
  node_commands["Request Commands<br/>[yt.md]"]
end

subgraph group_insight["Strategy and Research"]
  node_strategist["Channel Strategist"]
  node_auditor["Channel Auditor<br/>[channel-auditor.md]"]
  node_competitor["Competitor Analyst"]
  node_research["Research Agent<br/>[research-agent.md]"]
  node_research_report["Research Report"]
end

subgraph group_create["Content Production"]
  node_ideation["Ideation Agent<br/>[ideation-agent.md]"]
  node_script["Script Agent<br/>[script-agent.md]"]
  node_voice["Voice Agent<br/>[voice-agent.md]"]
end

subgraph group_growth["Publishing and Growth"]
  node_calendar["Calendar Agent<br/>[calendar-agent.md]"]
  node_thumbnail["Thumbnail Agent<br/>[thumbnail-agent.md]"]
  node_metadata["Metadata Agent<br/>[metadata-agent.md]"]
  node_seo["SEO Agent<br/>[seo-agent.md]"]
  node_shorts["Shorts Agent<br/>[shorts-agent.md]"]
  node_repurpose["Repurpose Agent<br/>[repurpose-agent.md]"]
  node_monetization["Monetization Agent"]
  node_analytics["Analytics Agent<br/>[analytics-agent.md]"]
end

subgraph group_runtime["Optional Data Tools"]
  node_transcribe["Voice Transcription"]
  node_recording_doc["Recording Document"]
  node_channel_data["Channel Data Fetch"]
  node_video_analytics["Video Analytics Fetch"]
  node_transcript["Transcript Fetch"]
  node_competitor_search["Competitor Video Search"]
  node_quota[("Quota Ledger<br/>[quota_tracker.py]")]
  node_auth["YouTube Authentication<br/>[youtube_auth.py]"]
end

node_creator(("Creator"))
node_youtube{{"YouTube APIs"}}

node_creator -->|"requests work"| node_orchestrator
node_orchestrator -->|"recognizes phrases"| node_commands
node_orchestrator -->|"routes setup"| node_strategist
node_orchestrator -->|"routes audits"| node_auditor
node_orchestrator -->|"routes analysis"| node_competitor
node_orchestrator -->|"routes research"| node_research
node_orchestrator -->|"routes reports"| node_research_report
node_orchestrator -->|"routes calendars"| node_calendar
node_orchestrator -->|"routes scripts"| node_script
node_orchestrator -->|"routes voice work"| node_voice
node_orchestrator -->|"routes thumbnails"| node_thumbnail
node_orchestrator -->|"routes metadata"| node_metadata
node_orchestrator -->|"routes SEO"| node_seo
node_orchestrator -->|"routes Shorts"| node_shorts
node_orchestrator -->|"routes repurposing"| node_repurpose
node_orchestrator -->|"routes monetization"| node_monetization
node_orchestrator -->|"routes analytics"| node_analytics
node_research -->|"provides research"| node_ideation
node_ideation -->|"presents idea choices"| node_creator
node_creator -->|"approves idea"| node_seo
node_seo -->|"sets title direction"| node_script
node_script -->|"presents variants"| node_creator
node_creator -->|"chooses variant"| node_script
node_script -.->|"renders recording script"| node_recording_doc
node_script -->|"feeds video package"| node_thumbnail
node_script -->|"feeds video package"| node_metadata
node_script -->|"feeds video package"| node_shorts
node_voice -.->|"transcribes voice samples"| node_transcribe
node_channel_data -->|"uses credentials"| node_auth
node_channel_data -->|"checks quota"| node_quota
node_video_analytics -->|"uses credentials"| node_auth
node_transcript -->|"uses credentials"| node_auth
node_transcript -->|"checks quota"| node_quota
node_competitor_search -->|"uses credentials"| node_auth
node_competitor_search -->|"checks quota"| node_quota
node_competitor_search -->|"imports duration parser"| node_channel_data
node_channel_data -.->|"fetches public data"| node_youtube
node_video_analytics -.->|"queries private analytics"| node_youtube
node_transcript -.->|"fetches captions"| node_youtube
node_competitor_search -.->|"searches videos"| node_youtube

click node_orchestrator "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/skills/orchestrator/SKILL.md"
click node_commands "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/commands/yt.md"
click node_strategist "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/channel-strategist.md"
click node_auditor "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/channel-auditor.md"
click node_competitor "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/competitor-analyst.md"
click node_research "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/research-agent.md"
click node_research_report "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/research-report-agent.md"
click node_ideation "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/ideation-agent.md"
click node_script "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/script-agent.md"
click node_voice "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/voice-agent.md"
click node_transcribe "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/transcribe_audio.py"
click node_recording_doc "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/build_reader_doc.py"
click node_calendar "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/calendar-agent.md"
click node_thumbnail "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/thumbnail-agent.md"
click node_metadata "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/metadata-agent.md"
click node_seo "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/seo-agent.md"
click node_shorts "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/shorts-agent.md"
click node_repurpose "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/repurpose-agent.md"
click node_monetization "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/monetization-agent.md"
click node_analytics "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/analytics-agent.md"
click node_channel_data "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/fetch_channel_data.py"
click node_video_analytics "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/fetch_video_analytics.py"
click node_transcript "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/fetch_transcript.py"
click node_competitor_search "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/search_competitor_videos.py"
click node_quota "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/utils/quota_tracker.py"
click node_auth "https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/utils/youtube_auth.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_orchestrator,node_commands toneBlue
class node_strategist,node_auditor,node_competitor,node_research,node_research_report toneAmber
class node_ideation,node_script,node_voice,node_youtube toneMint
class node_calendar,node_thumbnail,node_metadata,node_seo,node_shorts,node_repurpose,node_monetization,node_analytics toneRose
class node_transcribe,node_recording_doc,node_channel_data,node_video_analytics,node_transcript,node_competitor_search,node_quota,node_auth,node_creator toneIndigo
```

## Components

### Orchestration

- [Orchestrator](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/skills/orchestrator/SKILL.md): `skills/orchestrator/SKILL.md`
- [Request Commands](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/commands/yt.md): `commands/yt.md`

### Strategy and Research

- [Channel Strategist](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/channel-strategist.md): `agents/channel-strategist.md`
- [Channel Auditor](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/channel-auditor.md): `agents/channel-auditor.md`
- [Competitor Analyst](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/competitor-analyst.md): `agents/competitor-analyst.md`
- [Research Agent](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/research-agent.md): `agents/research-agent.md`
- [Research Report](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/research-report-agent.md): `agents/research-report-agent.md`

### Content Production

- [Ideation Agent](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/ideation-agent.md): `agents/ideation-agent.md`
- [Script Agent](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/script-agent.md): `agents/script-agent.md`
- [Voice Agent](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/voice-agent.md): `agents/voice-agent.md`

### Publishing and Growth

- [Calendar Agent](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/calendar-agent.md): `agents/calendar-agent.md`
- [Thumbnail Agent](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/thumbnail-agent.md): `agents/thumbnail-agent.md`
- [Metadata Agent](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/metadata-agent.md): `agents/metadata-agent.md`
- [SEO Agent](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/seo-agent.md): `agents/seo-agent.md`
- [Shorts Agent](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/shorts-agent.md): `agents/shorts-agent.md`
- [Repurpose Agent](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/repurpose-agent.md): `agents/repurpose-agent.md`
- [Monetization Agent](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/monetization-agent.md): `agents/monetization-agent.md`
- [Analytics Agent](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/agents/analytics-agent.md): `agents/analytics-agent.md`

### Optional Data Tools

- [Voice Transcription](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/transcribe_audio.py): `execution/transcribe_audio.py`
- [Recording Document](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/build_reader_doc.py): `execution/build_reader_doc.py`
- [Channel Data Fetch](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/fetch_channel_data.py): `execution/fetch_channel_data.py`
- [Video Analytics Fetch](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/fetch_video_analytics.py): `execution/fetch_video_analytics.py`
- [Transcript Fetch](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/fetch_transcript.py): `execution/fetch_transcript.py`
- [Competitor Video Search](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/search_competitor_videos.py): `execution/search_competitor_videos.py`
- [Quota Ledger](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/utils/quota_tracker.py): `execution/utils/quota_tracker.py`
- [YouTube Authentication](https://github.com/pedromeloofficial/youtube-agent-matrix/blob/main/execution/utils/youtube_auth.py): `execution/utils/youtube_auth.py`

### Other components

- **Creator**
- **YouTube APIs**

## Connections

- Creator → Orchestrator: requests work (evidence: `README.md`)
- Orchestrator → Request Commands: recognizes phrases (evidence: `README.md`)
- Orchestrator → Channel Strategist: routes setup (evidence: `README.md`)
- Orchestrator → Channel Auditor: routes audits (evidence: `README.md`)
- Orchestrator → Competitor Analyst: routes analysis (evidence: `README.md`)
- Orchestrator → Research Agent: routes research (evidence: `README.md`)
- Orchestrator → Research Report: routes reports (evidence: `README.md`)
- Orchestrator → Calendar Agent: routes calendars (evidence: `README.md`)
- Orchestrator → Script Agent: routes scripts (evidence: `README.md`)
- Orchestrator → Voice Agent: routes voice work (evidence: `README.md`)
- Orchestrator → Thumbnail Agent: routes thumbnails (evidence: `README.md`)
- Orchestrator → Metadata Agent: routes metadata (evidence: `README.md`)
- Orchestrator → SEO Agent: routes SEO (evidence: `README.md`)
- Orchestrator → Shorts Agent: routes Shorts (evidence: `README.md`)
- Orchestrator → Repurpose Agent: routes repurposing (evidence: `README.md`)
- Orchestrator → Monetization Agent: routes monetization (evidence: `README.md`)
- Orchestrator → Analytics Agent: routes analytics (evidence: `README.md`)
- Research Agent → Ideation Agent: provides research (evidence: `README.md`)
- Ideation Agent → Creator: presents idea choices (evidence: `README.md`)
- Creator → SEO Agent: approves idea (evidence: `README.md`)
- SEO Agent → Script Agent: sets title direction (evidence: `README.md`)
- Script Agent → Creator: presents variants (evidence: `README.md`)
- Creator → Script Agent: chooses variant (evidence: `README.md`)
- Script Agent → Recording Document: renders recording script
- Script Agent → Thumbnail Agent: feeds video package (evidence: `README.md`)
- Script Agent → Metadata Agent: feeds video package (evidence: `README.md`)
- Script Agent → Shorts Agent: feeds video package (evidence: `README.md`)
- Voice Agent → Voice Transcription: transcribes voice samples
- Channel Data Fetch → YouTube Authentication: uses credentials (evidence: `execution/fetch_channel_data.py`)
- Channel Data Fetch → Quota Ledger: checks quota (evidence: `execution/fetch_channel_data.py`)
- Video Analytics Fetch → YouTube Authentication: uses credentials (evidence: `execution/fetch_video_analytics.py`)
- Transcript Fetch → YouTube Authentication: uses credentials (evidence: `execution/fetch_transcript.py`)
- Transcript Fetch → Quota Ledger: checks quota (evidence: `execution/fetch_transcript.py`)
- Competitor Video Search → YouTube Authentication: uses credentials (evidence: `execution/search_competitor_videos.py`)
- Competitor Video Search → Quota Ledger: checks quota (evidence: `execution/search_competitor_videos.py`)
- Competitor Video Search → Channel Data Fetch: imports duration parser (evidence: `execution/search_competitor_videos.py`)
- Channel Data Fetch → YouTube APIs: fetches public data
- Video Analytics Fetch → YouTube APIs: queries private analytics
- Transcript Fetch → YouTube APIs: fetches captions
- Competitor Video Search → YouTube APIs: searches videos