{
  "markdown": "# Golpo Plugin for Claude Code and Codex\n\n[![CI](https://github.com/Golpo-AI/golpo-claude-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/Golpo-AI/golpo-claude-skill/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)]()\n[![Plugin: 0.2.0](https://img.shields.io/badge/plugin-v0.2.0-green.svg)]()\n\n> Generate AI videos with [Golpo](https://video.golpoai.com) directly from\n> Claude Code **or** Codex. Give the agent a prompt, a script, an audio file,\n> or a PDF — it submits the job, polls until it's done, **downloads the MP4\n> to your computer**, and shows you the file path plus the hosted URL.\n\n```text\nYou:   \"Make a 30-second video about why the sky is blue.\"\nAgent: ✓ Submitted (job 1b489b1c…). Polling…\n         status=generating … status=generating … status=completed\n       Saved to ~/Golpo/videos/20260429-015856_why-is-the-sky-blue_1b489b1c.mp4\n       Hosted at https://golpo-podcast-inputs.s3.us-east-2.amazonaws.com/files/894abde8-…mp4\n```\n\n> Real transcript from a smoke test. Filename and URLs are unaltered.\n\n---\n\n## Table of contents\n\n- [What it does](#what-it-does)\n- [Install](#install)\n- [First run](#first-run)\n- [Usage examples](#usage-examples)\n- [Where videos are saved](#where-videos-are-saved)\n- [The full input matrix](#the-full-input-matrix)\n- [Visual styles](#visual-styles)\n- [Voices, languages, music](#voices-languages-music)\n- [Direct CLI use](#direct-cli-use)\n- [File map](#file-map)\n- [How the skill works internally](#how-the-skill-works-internally)\n- [Troubleshooting](#troubleshooting)\n- [Self-hosting / forking](#self-hosting--forking)\n- [Pricing](#pricing)\n- [Links](#links)\n\n---\n\n## What it does\n\nThe plugin registers a skill named `golpo` (one helper script underneath) for\nboth **Claude Code** and **Codex**. When you ask the agent to make a video,\nthe skill:\n\n1. Verifies your environment (Python, `requests`, API key).\n2. Asks for your Golpo API key on first run, saves it to `~/.golpo/api_key`\n   with `0600` perms.\n3. Gathers requirements from your message — prompt, script, attachments,\n   duration, voice, language, style. Defaults are sensible so most asks need\n   no follow-up.\n4. Uploads any audio/document files (two-step: API call + S3 PUT).\n5. Submits the generate job, then polls the status endpoint with exponential\n   backoff. Resilient to transient 5xx errors.\n6. **Downloads the MP4 to `~/Golpo/videos/`** with a readable filename.\n7. Shows you the local file (clickable) and the hosted URL.\n\nIt supports both Golpo engines:\n- **Golpo Sketch** — whiteboard line-art animation (Classic, Improved,\n  Formal, Dry Erase, **Professional Clean**, Crayon).\n- **Golpo Canvas** — richer, image-driven look (Chalkboard B/W, Chalkboard\n  Color, Whiteboard, Modern Minimal, Playful, Technical, Editorial,\n  **Sharpie**), with optional drawing-cursor effects.\n\n---\n\n## Install\n\nThe same repo ships two plugin manifests — one for Claude Code\n(`plugins/golpo/.claude-plugin/plugin.json`) and one for Codex\n(`plugins/golpo/.codex-plugin/plugin.json`) — pointing at the same skill.\nInstall whichever matches the agent you use.\n\n### Claude Code\n\nIn the Claude Code terminal CLI:\n\n```text\n/plugin marketplace add Golpo-AI/golpo-claude-skill\n/plugin install golpo@GolpoSkill\n```\n\n> `golpo` is the plugin `name`; `GolpoSkill` is the marketplace `name`. Both\n> are case-sensitive.\n\n`/plugin update golpo` later when a new version ships.\n\n### Codex\n\nIn a terminal:\n\n```bash\ncodex plugin marketplace add Golpo-AI/golpo-claude-skill\n```\n\nThen in Codex:\n\n```text\ncodex\n/plugins\n```\n\nOpen the **GolpoSkill** marketplace tab, select **golpo**, and choose\n**Install plugin**.\n\nOr install everything from the CLI:\n\n```bash\ncodex plugin add golpo@GolpoSkill\n```\n\n### Manual (Claude Code)\n\n```bash\ngit clone https://github.com/Golpo-AI/golpo-claude-skill.git ~/.claude/plugins/golpo\n```\n\nRestart Claude Code.\n\n### Manual (Codex)\n\n```bash\ngit clone https://github.com/Golpo-AI/golpo-claude-skill.git ~/.codex/plugins/golpo\n```\n\nRestart Codex.\n\n### From a local checkout (for forks / dev)\n\n```bash\ngit clone https://github.com/Golpo-AI/golpo-claude-skill.git\ncd golpo-claude-skill\n# In Claude Code:\n#   /plugin marketplace add /absolute/path/to/golpo-claude-skill\n#   /plugin install golpo@GolpoSkill\n# In Codex:\n#   codex plugin marketplace add /absolute/path/to/golpo-claude-skill\n#   codex plugin add golpo@GolpoSkill\n```\n\n### Requirements\n\n- **Python 3.8+** (preinstalled on macOS and most Linux distros).\n- **`requests`** Python package — install with `pip3 install --user requests`\n  if missing. The skill prompts you with the exact command.\n- **A Golpo API key** — get one at https://video.golpoai.com (API tier:\n  $200 minimum entry, $1 = 1 credit, 2 credits per minute of video).\n\n---\n\n## First run\n\nThe first time you ask the agent to make a video:\n\n1. It runs `golpo.py check` and notices `key_configured=false`.\n2. It explains that the skill needs your API key, then asks you to paste it.\n3. Behind the scenes it runs `golpo.py auth --key <YOUR_KEY>`.\n4. Subsequent invocations skip auth.\n\nThe key lives at `~/.golpo/api_key` (mode `0600`). To rotate later (replace\n`~/.claude/plugins` with `~/.codex/plugins` if you're on Codex):\n\n```bash\npython3 ~/.claude/plugins/golpo/skills/golpo/scripts/golpo.py auth --key NEW_KEY --force\n```\n\nTo use an env var instead (overrides the file):\n\n```bash\nexport GOLPO_API_KEY=...\n```\n\n---\n\n## Usage examples\n\nJust talk to the agent in plain English:\n\n| You say | The agent does |\n|---|---|\n| \"Make a 30-second video about why the sky is blue.\" | Prompt → Sketch Classic, default voice, 0.5 min |\n| \"Make it a vertical short with marker style.\" | Adds `--video_type short --use_2_0_style true --image_style marker` |\n| \"Use this script: \\<paste\\>\" | Adds `--new_script \"...\"` (and bumps timing if your script is longer than the requested duration) |\n| \"Use my voice from `~/voice.mp3`.\" | Calls `upload`, then `--audio_clip <url>` |\n| \"Summarize this PDF: `~/report.pdf`.\" | Calls `upload`, then `--upload_urls <url>` |\n| \"Hindi narration with English captions.\" | `--language hi --display_language en` (Canvas only) |\n| \"Save it to `~/Desktop/clips/` instead.\" | Adds `--output_dir ~/Desktop/clips/` |\n| \"Don't download, just give me the URL.\" | Adds `--no_download` |\n| \"List my last 5 videos.\" | `golpo.py list --limit 5` |\n| \"Re-download video `<id>`.\" | `golpo.py get <id>` |\n\n---\n\n## Where videos are saved\n\n**Default:** `~/Golpo/videos/`\n\n**Filename pattern:**\n```\nYYYYMMDD-HHMMSS_<title-slug>_<video-id-short>.mp4\n```\n\nThe slug comes from the API-canonical video title (what `golpo.py list` and\nthe Golpo dashboard show), so files match the names you see elsewhere.\n\nFor example:\n```\n~/Golpo/videos/20260429-015405_why-is-the-sky-blue_a1b2c3d4.mp4\n~/Golpo/videos/20260429-015628_summarize-this-document-about-ocean-tides_b18d3425.mp4\n```\n\n**Override per-video:**\n```bash\npython3 .../golpo.py generate --prompt \"...\" --output_dir ~/Desktop/clips/\n```\n…or just say to Claude \"save it to ~/Desktop/clips/\".\n\n**Override globally:**\n```bash\nexport GOLPO_VIDEO_DIR=~/Desktop/clips\n```\n\n**Skip the download (URL only):**\n```bash\npython3 .../golpo.py generate --prompt \"...\" --no_download\n```\n\nThe hosted URL is always printed too, so you can share without downloading.\n\n---\n\n## The full input matrix\n\n| Input | Required field | Optional with |\n|---|---|---|\n| **Prompt only** | `--prompt \"...\"` | any styling, voice, language, music |\n| **Prompt + custom script** | `--prompt \"...\" --new_script \"...\"` | (script length must fit the chosen `--timing`) |\n| **Audio narration** | `--prompt \"...\" --audio_clip <url>` | upload first; ≤ 15 MB |\n| **Document(s)** | `--prompt \"...\" --upload_urls <url>` (repeatable) | PDF/DOCX/PPTX/TXT, ≤ 15 MB each, **single-use** |\n| **Embed images** | `--user_images <url>` + `--user_images_descriptions \"...\"` | per-image `--use_as_is` / `--skip_animation` flags |\n| **Embed videos** | `--user_videos <url>` + `--user_videos_description \"...\"` | optional `--user_audio_in_video <idx>` |\n| **Custom logo** | `--logo <url>` | `--logo_placement tl|tr|bl|br` |\n\n> `prompt` is **always required**, even when also passing `audio_clip` /\n> `new_script` / `upload_urls`. The Golpo backend uses it as the title /\n> framing.\n\n---\n\n## Visual styles\n\n### Golpo Sketch — `--use_lineart_2_style <value>`\n\nWhiteboard line-art animation. Pass as a **string**.\n\n| Value | Style name | Description |\n|---|---|---|\n| `false` | Classic (default) | Original Golpo Sketch — whiteboard line-art |\n| `true` | Improved (BETA) | Cleaner strokes, more polished |\n| `advanced` | Formal | Higher detail, refined aesthetics |\n| `whiteboard` | Dry Erase | Smooth marker-like strokes |\n| `modern_minimal` | **Professional Clean** | Geometric shapes with indigo accent |\n| `storytelling` | Crayon | Hand-drawn crayon and colored pencil |\n\n### Golpo Canvas — `--use_2_0_style true --image_style <value>`\n\nRicher, image-driven look.\n\n| `--image_style` | Label | Description |\n|---|---|---|\n| `chalkboard_white` | Chalkboard (B/W) (default) | Black & white chalkboard |\n| `neon` | Chalkboard Color | Colorful neon chalkboard |\n| `whiteboard` | Whiteboard | Clean whiteboard illustrations |\n| `modern_minimal` | Modern Minimal | Sleek, minimal aesthetic |\n| `playful` | Playful | Fun, colorful illustrations |\n| `technical` | Technical | Diagrammatic style |\n| `editorial` | Editorial | Magazine-style illustration |\n| `marker` | **Sharpie** | Bold marker/sharpie drawn |\n\nAdd a drawing-cursor effect on Canvas: `--pen_style stylus|marker|pen`.\n\n> **Sketch and Canvas are mutually exclusive.** Pick one engine per video.\n\n---\n\n## Voices, languages, music\n\n**Voices** (`--style`):\n- `solo-female-3` (default) — warm, neutral\n- `solo-female-4` — brighter, energetic\n- `solo-male-3` — calm, authoritative\n- `solo-male-4` — deeper, dramatic\n\n**Languages** (`--language`):\n44+ codes. Common: `en` (default), `hi`, `es`, `fr`, `de`, `pt`, `ja`, `ko`,\n`zh`, `ar`, `bn`, `ta`, `ur`. Full list:\n[references/languages.md](plugins/golpo/skills/golpo/references/languages.md).\n\n**Background music** (`--bg_music`):\n`jazz`, `lofi`, `whimsical`, `dramatic`, `engaging`, `hyper`, `inspirational`,\n`documentary`. Omit for narration-only audio.\n\n---\n\n## Direct CLI use\n\nThe helper is a standalone CLI — Claude Code and Codex are just two\nfront-ends. Path is `~/.claude/plugins/...` on Claude Code,\n`~/.codex/plugins/...` on Codex.\n\n```bash\nHELPER=~/.claude/plugins/golpo/skills/golpo/scripts/golpo.py\n# or: HELPER=~/.codex/plugins/golpo/skills/golpo/scripts/golpo.py\n\n# Sanity check\npython3 \"$HELPER\" check\n\n# Save the API key\npython3 \"$HELPER\" auth --key sk-...\n\n# Upload an attachment\npython3 \"$HELPER\" upload ~/report.pdf\n# -> FILE_URL=https://...\n\n# Generate (auto-downloads to ~/Golpo/videos/)\npython3 \"$HELPER\" generate \\\n  --prompt \"Summarize this report\" \\\n  --upload_urls \"https://...\" \\\n  --use_2_0_style true --image_style marker --pen_style stylus \\\n  --timing 1 --video_type long\n# -> JOB_ID=...\n# -> progress=0% status=generating\n# -> ...\n# -> VIDEO_FILE=/Users/you/Golpo/videos/20260429-015405_summarize-this-report_b18d3425.mp4\n# -> VIDEO_URL=https://...\n\n# Manage existing videos\npython3 \"$HELPER\" list --limit 10\npython3 \"$HELPER\" get <video_id>      # re-downloads\npython3 \"$HELPER\" get <video_id> --no_download\npython3 \"$HELPER\" status <job_id>\n```\n\n`python3 \"$HELPER\" generate --help` lists every flag.\n\n---\n\n## File map\n\n```\ngolpo-claude-skill/                  # repo root (hosts both marketplaces)\n├── .claude-plugin/\n│   └── marketplace.json             # Claude Code marketplace\n├── .agents/\n│   └── plugins/\n│       └── marketplace.json         # Codex marketplace\n├── plugins/\n│   └── golpo/                       # plugin root (shared)\n│       ├── .claude-plugin/\n│       │   └── plugin.json          # Claude Code plugin manifest\n│       ├── .codex-plugin/\n│       │   └── plugin.json          # Codex plugin manifest\n│       └── skills/\n│           └── golpo/                # the skill (shared)\n│               ├── SKILL.md          # instructions the agent follows\n│               ├── QUICKSTART.md     # human-friendly cheat sheet\n│               ├── scripts/\n│               │   ├── golpo.py      # CLI helper\n│               │   └── requirements.txt\n│               └── references/       # loaded on demand\n│                   ├── voices.md\n│                   ├── styles.md\n│                   ├── languages.md\n│                   ├── bg_music.md\n│                   └── full-payload.md\n├── README.md                         # this file\n└── LICENSE\n```\n\n---\n\n## How the skill works internally\n\n1. **Trigger.** The agent (Claude Code or Codex) matches the user's message\n   against the `description` field of\n   [SKILL.md](plugins/golpo/skills/golpo/SKILL.md). The skill fires on\n   phrasing like \"make a video\", \"create an explainer\", \"summarize this PDF\n   as a video\", etc.\n2. **Bootstrap.** It runs `golpo.py check` to confirm Python, `requests`,\n   and the API key are in place. The helper uses `$CLAUDE_PLUGIN_ROOT` to\n   locate itself; Codex exposes this as a legacy-compatible env var, so the\n   same script works in both runtimes.\n3. **Auth (first run).** If no key, the agent asks for it and saves it via\n   `golpo.py auth --key <KEY>`.\n4. **Plan.** The agent turns the user's intent into a concrete payload,\n   defaulting anything they didn't specify.\n5. **Upload.** For audio or document inputs, it calls `golpo.py upload`\n   per file. The helper does the two-step flow: POST to\n   `/api/v1/videos/upload-file` to get a presigned S3 URL, then PUT the file\n   to that URL.\n6. **Generate.** `golpo.py generate` POSTs `/api/v1/videos/generate` with the\n   payload, captures `job_id` and `video_id`, and polls\n   `/api/v1/videos/status/{job_id}` until terminal. Polling backs off\n   exponentially (5 s → 30 s) and retries 5xx up to 5 times.\n7. **Download.** When the API returns `video_url`, the helper streams the MP4\n   to `~/Golpo/videos/` (or your override) with a readable filename.\n8. **Report.** Helper prints `VIDEO_FILE=<path>` and `VIDEO_URL=<url>`. The\n   agent shows both to you with a clickable file link.\n\n---\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---|---|\n| `requests_ok=false` from `check` | `pip3 install --user requests` |\n| `ERROR: 401 Unauthorized` | API key rejected: `auth --key NEW --force` |\n| `ERROR: 403 Forbidden` | Plan doesn't include the action; visit https://video.golpoai.com |\n| `ERROR: 422` with `timing` complaint | Pass timing as a string: `--timing 0.5`, not `0.5` (the helper does this for you, but check your call) |\n| `ERROR: 422 script duration N min > timing M min` | Bump `--timing` higher than `N` |\n| `ERROR: 429 Rate limited` | Cap parallel jobs at 3; back off and retry |\n| `WARNING: download failed` | Hosted URL still printed; download manually with `curl` or retry `golpo.py get <video_id>` |\n| Job times out at 90 min | `--max_wait_seconds 10800` to extend further, or resume later: `golpo.py status <JOB_ID>` |\n| Document URL fails on second use | Document URLs are **single-use**; re-upload the file |\n| `--use_lineart_2_style` and `--use_2_0_style` both set | Pick one — Sketch and Canvas are mutually exclusive |\n\n---\n\n## Self-hosting / forking\n\nTo run this from your own GitHub repo:\n\n1. Fork or clone this repo and push to your `<org>/<repo>`.\n2. Tell users:\n   ```text\n   # Claude Code\n   /plugin marketplace add <your-org>/<repo>\n   /plugin install golpo@GolpoSkill\n\n   # Codex\n   codex plugin marketplace add <your-org>/<repo>\n   codex plugin add golpo@GolpoSkill\n   ```\n3. When shipping changes, bump `version` in **all four** spots and keep them\n   in sync:\n   - [plugins/golpo/.claude-plugin/plugin.json](plugins/golpo/.claude-plugin/plugin.json)\n   - [plugins/golpo/.codex-plugin/plugin.json](plugins/golpo/.codex-plugin/plugin.json)\n   - [.claude-plugin/marketplace.json](.claude-plugin/marketplace.json)\n   - [.agents/plugins/marketplace.json](.agents/plugins/marketplace.json)\n\n   Then optionally tag a release:\n   ```bash\n   git tag v0.2.0\n   git push --tags\n   ```\n\nEnd users update with `/plugin update golpo` (Claude Code) or\n`codex plugin marketplace upgrade` (Codex).\n\n---\n\n## Pricing\n\n- **API tier minimum:** $200 USD = 200 credits.\n- **Cost per credit:** $1 USD = 1 credit.\n- **Video cost:** 2 credits per minute of generated video → ~$0.50 for a\n  15-second video, $2 for a one-minute video.\n\nThe helper does not surface pricing — Golpo's billing happens server-side.\nCheck your usage at https://video.golpoai.com.\n\n---\n\n## Links\n\n- **Golpo:** https://video.golpoai.com\n- **API docs:** https://video.golpoai.com/api-docs/endpoints/v1\n- **Payload examples:** https://video.golpoai.com/guide/golpo-ai-video-api-payload-examples\n- **Issue tracker:** https://github.com/Golpo-AI/golpo-claude-skill/issues\n- **License:** [MIT](LICENSE)\n",
  "bytes": 16939,
  "sha": "3e775da7f53a21a7050334b3a0cc773110352e5b5e08c25c1193db40030244ca",
  "repo_slug": "golpo-ai/golpo-claude-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_golpo_ai_golpo_claude_skill_golpo_video_39e85b57/readme"
}