castloop

The multi-agent content pipeline that doesn't break in production.

castloop runs a full social-video content cycle with AI in every seat — research → brand-voice script → talking-head video with natural-language-directed B-roll → publish → analytics → redesign brief for the next cycle — and treats the thing that kills multi-agent pipelines as the core design problem: every handoff between agents is judged, traced, and fails closed.

research ─▶ script ─▶ avatar ─▶ transcript ─▶ direct ─▶ edit ─▶ ⛔ gate ─▶ publish ─▶ analyze ─▶ redesign ─┐
   ▲            each handoff: contract-validated + judged for fabrication + traced                        │
   └──────────────────────────────── the loop closes: analytics feed the next cycle ──────────────────────┘

Why

Multi-agent content pipelines break in production, and everyone who has run one knows how: every handoff loses context, and by the fourth agent in the chain the output is quietly made up. Meanwhile the tooling landscape splits into creation/scheduling tools (Postiz, Buffer, Blotato) and analytics tools (Socialinsider et al.) that never talk to each other — the step where a human reads the numbers and decides what to make next never got automated.

castloop closes both gaps:

• Structural context: every role receives the full accumulated cycle state, not just the previous role's output. Context loss is mitigated by architecture, not by prompt engineering.
• A judge at every handoff: after each role runs, an LLM judge extracts the claims in its output and verifies them against the facts already in the cycle. A script that invents a statistic gets rejected, the judge's reason is injected into the retry, and a second failure blocks the cycle instead of shipping slop. The judge fails closed: unparseable verdict or judge downtime = rejection, never a silent pass.
• A human gate before publishing — enforced in code and bound to the content. You cannot approve a cycle that has no script or no rendered video, and the approval stores a hash of what you saw: swap the file or re-render afterwards and the gate halts the cycle for re-review. Paid, irreversible steps are never retried blindly, runs take an exclusive lock on their cycle, and every accepted handoff is checkpointed so a crash never re-bills work that already completed.
• The loop actually closes: the analyst measures your posts (and public competitor snapshots), and the redesigner turns those numbers into the brief for the next cycle — insights must cite figures that exist in the report, or the judge rejects them too.

Who it's for: creators and small teams producing short-form video across platforms who want automation without publishing unreviewed AI output.

Quickstart

npm install -g castloop     # or: npx castloop

castloop demo               # deterministic replay, mocks only, zero cost
castloop init               # scaffold .castlooprc.json
castloop run                # run a cycle — halts at the approval gate
castloop approve <cycleId>  # review the content, then approve it
castloop run --cycle <id>   # resume: publish → analytics → redesign
castloop run --from <id>    # start the next cycle from this one's redesign
castloop trace <cycleId>    # see every handoff, retry and rejection
castloop doctor             # check config and environment

castloop demo needs no keys and makes no network calls — it replays the two scenes that define the project: a full cycle stopping at the approval gate, and a fabricated claim being caught at a handoff, corrected via feedback, and passing on retry.

Real mode

castloop run uses deterministic mocks until you explicitly opt in to spending money:

1. In .castlooprc.json: set providers.mode to "real", fill providers.heygen (avatarId, voiceId) and providers.postiz (baseUrl, integrations); optionally providers.youtube.competitors.
2. Export the keys: CASTLOOP_ANTHROPIC_API_KEY, HEYGEN_API_KEY, OPENAI_API_KEY, MUAPI_KEY, POSTIZ_API_KEY, YOUTUBE_API_KEY.
3. castloop doctor verifies config and environment before you spend a cent; castloop run then executes the real pipeline — LLM handoff judge and brand-voice guard included — and prints a spend warning.

The grounding judge runs on the roles where fabrication is possible and checkable (scriptwriter, director, redesigner); roles that introduce new external facts (real post ids, measured metrics, mechanical timestamps) are covered by contract validation instead — see DECISIONS.md.

The natural-language director

You don't need to know editing vocabulary. The director role takes your script and the word-level transcript of the recorded clip and turns intent like "when I mention the pipeline, show a diagram behind me" into timed B-roll cues. Whatever the LLM proposes is then deterministically sanitized — cues are clamped to the clip and overlaps resolved — so the edit plan is always physically valid. While B-roll shows, the speaker moves to a corner picture-in-picture; captions follow the transcript word by word.

Providers

Every external service sits behind a small interface with three implementations: real, mock (deterministic, for tests) and replay (for the demo). Swap any of them without touching the pipeline.

| Piece | v0.1 provider | Interface | |---|---|---| | Script/judge LLM | Anthropic (no SDK, plain fetch) | LlmClient | | Narration / talking head | OpenAI TTS voiceover (default) or HeyGen | AvatarProvider | | Transcription | OpenAI Whisper (word timestamps) | TranscriptionProvider | | B-roll generation | MuAPI (flux-dev et al.) | AssetProvider | | Composition/render | Remotion | RenderProvider | | Publishing | Postiz (self-hosted or cloud) | PublishProvider | | Analytics | YouTube Data API (public metadata) | AnalyticsProvider |

Costs

Development, CI and the demo run on mocks: $0. A real ~60s cycle:

| Item | Provider | Faceless (default) | With talking head | |---|---|---|---| | Narration / avatar | OpenAI TTS · HeyGen | ~$0.02 | ~$3.00 | | Transcription | Whisper | ~$0.01 | ~$0.01 | | B-roll (5 images) | MuAPI | ~$0.10–0.45 | ~$0.10–0.45 | | LLM calls (roles + judges) | Anthropic | ~$0.10–0.20 | ~$0.10–0.20 | | Publish / analytics | Postiz self-hosted / YouTube API | ~$0 | ~$0 | | Total per cycle | | ≈ $0.25 | ≈ $3.20–3.70 |

Two shapes of short-form video, one pipeline. Faceless (default, providers.avatar: "voiceover"): TTS narration over full-frame B-roll with captions — cents per cycle, no avatar account. Talking head ("heygen"): you on screen, moving to a corner picture-in-picture whenever B-roll plays. Both go through the same director, judge and gate.

Security considerations

• No competitor surveillance. Official platform APIs prohibit it, and scraping violates their terms of service. Competitor analysis is limited to public YouTube metadata via the official Data API, and a policy test fails the build if Instagram/TikTok data-collection code ever appears in src/providers. Publishing to those platforms through Postiz is fine; collecting data from them is not.
• API keys are read from environment variables; nothing is written to disk except cycle state and traces (local .castloop/, gitignored).
• The approval gate is enforced in code. --no-gate exists for genuinely unattended setups and prints a warning banner on every run.

Honest limitations

• v0.1 directs edits single-shot: keyword/mention → cue. There is no multi-turn conversational refinement of an existing edit plan yet — you adjust the brief or script and re-run the role.
• B-roll in v0.1 is generated images (video cues fall back to stills).
• The analytics loop is only as good as what platforms expose: YouTube public metadata today; deeper multi-platform analytics needs a provider you bring yourself (AnalyticsProvider is a small interface).
• The LLM judge reduces fabrication dramatically but is itself an LLM; the approval gate exists because no judge is perfect.
• Rendering uses Remotion, which has its own license (free for individuals and small teams).

Work with me

I design and operate multi-agent AI systems in production for real businesses — this project is a working sample of how I think about orchestration, evals and human-in-the-loop control.

• Site: nestormartinez.dev
• Email: [email protected]
• LinkedIn: Néstor Martínez

License

MIT