KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #claude-code #codex #developer-tools #open-source #agent-skills #ai #dsh-plugin #llm #windows

ugc-ad-agent

★ 6 Open GitHub ↗

Claude Code + Arcads agent that writes, scores, and ships UGC ads on autopilot.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# UGC Ad Agent (Claude + Arcads)

A Claude Code agent that turns a one-page product brief into 20 scored short-form ad scripts, picks the best 3, generates them through the Arcads API, and downloads finished MP4s to your desktop.

## What you need

- macOS or Linux
- Python 3.9+
- [Claude Code](https://claude.com/claude-code)
- An [Arcads](https://arcads.ai) account with API access

## Setup

1. Drop this folder anywhere. Location doesn't matter.

2. Add your Arcads credentials:
   ```
   cp .env.example .env
   ```
   Then paste your `ARCADS_CLIENT_ID` and `ARCADS_CLIENT_SECRET` into `.env`. Find them in the Arcads dashboard under API access.

3. Install dependencies:
   ```
   python3 -m pip install -r requirements.txt
   ```

4. Confirm auth:
   ```
   python3 -m tools.arcads_client
   ```
   You should see `Arcads credentials OK.`

5. Open the folder in Claude Code (`claude` from this directory).

## First run

1. Copy `briefs/_template.md` to `briefs/<your-product>.md` and fill it in. Don't skip the verbatim customer reviews and pain points — those are the only things stopping the scripts from sounding generic.

2. Tell Claude `run`. The agent will:
   - Write 20 scripts and score each /10
   - Pick the top 3
   - Match each to an Arcads actor
   - Trigger generation through the API
   - Poll every 30s and download MP4s to `videos/<date>/`
   - Log the batch to `runs.md`

3. Total time: ~15-30 minutes (mostly the Arcads render queue).

## Self-improvement (the 48-hour loop)

After your batch ships and you have ad performance data, append `WINNERS:` and `LOSERS:` tags to your `runs.md` entry:

```
## Batch 2026-04-22
WINNERS: scripts #3 and #7 — stat-led hooks with cost-comparison framing landed best
LOSERS: scripts #1 and #2 — question hooks fell flat for this audience
NOTES: keep leaning on cost-comparison hooks for this customer
```

The agent reads the last 3 batches before writing your next one. 60%+ of the next 20 scripts will lean on what's actually winning.

## Files

```
CLAUDE.md       The agent's brain — don't edit unless you know why
.env            Your credentials (gitignored, don't share)
briefs/         One .md per product — start from _template.md
scripts/        Generated script batches with scores and selections
videos/         Finished MP4s
runs.md         Append-only performance log
tools/          Arcads API wrapper + runners
```

## Troubleshooting

- **`401 Unauthorized`** — credentials wrong. Re-check `.env`.
- **`429 Too Many Requests`** — rate-limited. The client backs off automatically (60s > 120s > 240s).
- **Poll stuck on `still_pending` for 10+ minutes** — usually the laptop slept. The wall-clock poller will catch up.
- **Need to resume an interrupted batch** — `python3 -m tools.poll_and_download <YYYY-MM-DD>` will pick up the known script IDs from `scripts/<date>/run_log.jsonl`.
- **`status: "generated"` but a 404 trying to download** — the asset's URL is pre-populated; the next poll will find the real file.

## What this isn't

- A replacement for taste. The rubric tells you which hooks landed structurally — you still pick the brand voice and flag what to test.
- A way to skip strategy. A bad brief produces 20 bad scripts.
- A guarantee. Watch performance, tag winners, let the agent learn.

That's it. Drop a brief in, type `run`, watch the videos land.

ugc-ad-agent

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README