# transcribe-agent Make any agent transcribe. One repo with three ways in: a pure-JSON CLI (`transcribe-so`), an agent skill for `npx skills add`, and a Claude Code plugin bundling the transcribe.so remote MCP server. transcribe.so turns YouTube videos, podcasts, direct media URLs, and local files into speaker-labelled transcripts with timestamped segments, chapters, sections, cited Q&A, subtitle files (SRT, VTT, karaoke VTT), full transcript exports, segment search, and paste-ready captions for Instagram, X, Threads, LinkedIn, YouTube, Spotify and Apple Podcasts. ## Install Keep a human in the loop: every paid call takes a max_charge_usd ceiling, and a free quote comes first. ### 1. Agent skill (Claude Code, OpenClaw, any skills.sh-compatible agent) ```bash npx skills add shsunmoonlee/transcribe-agent ``` This installs [SKILL.md](SKILL.md), which teaches the agent the CLI workflow, hard rules, and exit codes. ### 2. Claude Code plugin (remote MCP server + skills + /transcribe command) ``` /plugin marketplace add shsunmoonlee/transcribe-agent /plugin install transcribe-so@transcribe-agent ``` The plugin connects Claude to the remote MCP server at `https://transcribe.so/mcp` (24 tools) and bundles the `transcribe-audio` and `get-transcript` skills plus a one-shot `/transcribe` command. First tool call triggers the OAuth browser flow; alternatively authenticate with a `tsk_live_*` API key via `/mcp`. ### 3. CLI (any script, cron job, or agent with a shell) ```bash npm install -g transcribe-so # or: pnpm install -g transcribe-so export TRANSCRIBE_API_KEY=tsk_live_... # https://transcribe.so/settings/api-keys transcribe-so me ``` ### Codex As a plugin (remote MCP server plus the skills): ```bash codex plugin marketplace add shsunmoonlee/transcribe-agent codex plugin add transcribe-so@transcribe-agent ``` Or just the MCP server: ```bash codex mcp add transcribe --url https://transcribe.so/mcp ``` Codex opens the OAuth flow on the first tool call. The plugin ships [.codex-plugin/plugin.json](.codex-plugin/plugin.json) and [.agents/plugins/marketplace.json](.agents/plugins/marketplace.json). ### Grok This repo ships [.grok-plugin/plugin.json](.grok-plugin/plugin.json); Grok Build reads the root `.mcp.json` and `skills/` from it. ### Cursor From the marketplace or the Customize panel: find `transcribe-so` and click Install. Or add it to `.cursor/mcp.json` by hand: ```json {"mcpServers":{"transcribe":{"url":"https://transcribe.so/mcp"}}} ``` ### Antigravity CLI ```bash agy plugin install https://github.com/shsunmoonlee/transcribe-agent ``` The plugin ships [plugin.json](plugin.json) and [mcp_config.json](mcp_config.json), which point Antigravity CLI at the hosted MCP server, plus the skills in `skills/`. Antigravity CLI cannot run the OAuth sign-in itself (its `/mcp` panel shows "Auth Needed"), so connect the tools with an API key from https://transcribe.so/settings/api-keys: ```bash agy mcp add --header "Authorization: Bearer tsk_live_..." transcribe-so-key https://transcribe.so/mcp ``` Use a name other than `transcribe-so`: MCP server names are global in Antigravity, and the plugin's own `transcribe-so` entry keeps showing "Auth Needed" in the CLI, which you can ignore. The Antigravity App and IDE also offer an Authenticate button for the plugin's server (Settings, Customizations). Already used the Gemini CLI extension? `agy plugin import gemini` converts it. ### Gemini CLI ```bash gemini extensions install https://github.com/shsunmoonlee/transcribe-agent ``` The extension ships [gemini-extension.json](gemini-extension.json), which points Gemini CLI at the hosted MCP server. It opens a browser to sign in on first use. Since 2026-06-18 Gemini CLI serves paid Gemini API and enterprise keys; individual Google AI accounts use Antigravity CLI (above). ### ChatGPT Settings, Connectors, Developer mode, then add `https://transcribe.so/mcp` and sign in with your transcribe.so account. ### OpenClaw and any skills.sh agent ```bash npx skills add shsunmoonlee/transcribe-agent ``` Same command as entry 1 above: the skill is runtime-agnostic and teaches the CLI workflow, hard rules, and exit codes. ## CLI in 30 seconds ```bash # Price it (free), then transcribe under an explicit budget transcribe-so quote --source youtube --url "https://www.youtube.com/watch?v=..." transcribe-so run --source youtube --url "https://www.youtube.com/watch?v=..." --max-usd 2 # Local file transcribe-so upload ./interview.mp3 # prints upload_id (+ ffprobe duration) transcribe-so run --source upload --upload-id --duration --max-usd 5 # Artifacts transcribe-so result | jq '.chapters[]' transcribe-so transcript > out.txt # the whole transcript, never capped transcribe-so subtitles --format srt > out.srt transcribe-so captions --for instagram --variant highlights transcribe-so search "pricing" | jq -r '.hits[] | "\(.speaker): \(.text)"' transcribe-so ask -q "What did the guest say about pricing?" ``` ## Commands | Command | What it does | |---------|--------------| | `auth:status` | Is `TRANSCRIBE_API_KEY` valid? | | `me` | Account, wallet balance, plan limits, API-key scopes and spend | | `capabilities` | One JSON object: account + pipeline catalog + every format enum + exit codes | | `pipelines` | Per-minute pricing and supported languages | | `quote` | Free price preview (does not queue anything) | | `create` | Submit a job. `--max-charge-usd ` caps the charge server-side | | `run` | quote → budget gate → create → wait → result, in one command | | `wait ` | Long-poll to a terminal status | | `result ` | Chapters, sections, Q&A (`--include`, `--segments-offset`, `--segments-limit`) | | `transcript ` | **Raw**: the complete transcript, `txt` or `md`, never capped | | `subtitles ` | **Raw**: SRT / VTT / karaoke VTT / JSON | | `captions --for ` | **Raw**: paste-ready caption or chapter timestamps per platform | | `search ` | "Who said X, and when", library-wide or `--id`-scoped | | `ask -q "..."` | Cited Q&A (daily allowance, never the wallet) | | `list` / `get ` | Browse jobs; status/stage/progress snapshot | | `upload ` | Presigned PUT for a local file; prints `upload_id` | | `retry --yes` | New paid attempt (pass `--max-charge-usd` again) | | `delete --yes` | Irreversible | Design contract, made for agents: - stdout is JSON everywhere except the three raw-output commands (`subtitles`, `transcript`, and `captions` without `--json`), which print a body you can pipe to a file. Errors are always the JSON envelope. All progress goes to stderr, so `| jq .` always works. - Exit codes are meaningful: 0 ok, 1 API error, 2 usage, 3 auth, 4 payment, 5 transient, 6 local `--max-usd` budget refusal, 7 server-side `max_charge_exceeded` (nothing charged, no job started). - Two budgets, both explicit: `run --max-usd` refuses locally from the free quote; `--max-charge-usd` is sent to the API and enforced at the wallet hold. `run` sends its `--max-usd` as the server ceiling too unless you pass `--no-server-ceiling`. - `create`/`run`/`quote`/`retry` always send an `Idempotency-Key`. Pass `--idempotency-key` explicitly to make a retry safe across processes: the auto-generated one is per invocation, so re-running a command is a second key and a second charge. - A 409 `not_ready` is acted on by its `reason`: only `transcription_processing` is ever retried. - The CLI refuses to send your API key to a non-default host unless you pass `--allow-custom-host`. Full command reference and workflow rules: [SKILL.md](SKILL.md). Release notes: [CHANGELOG.md](CHANGELOG.md). Worked examples: [examples/](examples/). ## Pricing Transcription is billed per minute from your transcribe.so wallet; quotes are free (`quote` before committing). Clip renders are billed per started 60 s. Live Q&A uses a daily allowance, never the wallet. Current prices: ## Directories The plugin manifests (`.codex-plugin`, `.claude-plugin`, `.cursor-plugin`, `.grok-plugin`, `gemini-extension.json`) are versioned together and track the MCP server version; the CLI in `package.json` has its own version. Build the OpenAI Plugins Directory submission ZIP: ```bash pnpm run build:openai-plugin -- --video-url https://.../demo.mp4 # or DEMO_RECORDING_URL=... # -> out/transcribe-so-openai-plugin.zip (.codex-plugin/plugin.json, .mcp.json, skills/, assets/) ``` The script fails when model-readable copy breaks the listing rule: the `interface` block, release notes, `skills/**/SKILL.md`, `commands/*.md` and every manifest description carry no money, promotion or account-tier wording, no em-dashes, and no links outside transcribe.so and github.com. The agent learns what `getQuote` reports and when to ask the user before starting, nothing more. It also fails when the manifests disagree on the version or when `skills/` holds anything but `/SKILL.md`. Rules: . The root [SKILL.md](SKILL.md) documents the CLI for `npx skills add` and is not part of any directory listing; CLI flags such as `--max-charge-usd` live there. ## What the Claude plugin runs and sends - **One remote MCP server**, declared in [.mcp.json](.mcp.json): `https://transcribe.so/mcp` over HTTPS. Claude sends it the links, questions and transcript ids you give it, and it returns transcripts, chapters, answers, subtitle files and clip links. Sign-in is OAuth in your browser on the first tool call, or a transcribe.so API key you enter through `/mcp`. - **Local files, Claude Code only, when you ask for one:** `createUpload` returns a short-lived presigned HTTPS URL for transcribe.so's file storage on Cloudflare R2 (an `r2.cloudflarestorage.com` address), and Claude sends the file there with an HTTP PUT. Chat clients never upload files. - **Nothing else:** no hooks, no local server, no package downloads, no telemetry, and no credentials read from your machine. The skills and the `/transcribe` command are Markdown instructions for Claude. - Starting a transcription or rendering a clip draws on your transcribe.so account balance. Claude checks the free quote first and asks before it starts anything, unless you already gave it a spending limit. ## Privacy Policy This tooling sends the media URLs, uploaded files, and questions you provide to transcribe.so for processing. See the transcribe.so privacy policy at for data collection, usage, storage, retention, and contact information. No data is collected by the CLI or plugin itself beyond what the API and MCP tools transmit. ## Links - Agent landing page: - Docs: - OpenAPI: - MCP server card: - Auth guide: - Support: support@transcribe.so