{
  "markdown": "# TwelveLabs Claude Code Plugin\n\nIndex, search, and analyze videos directly from Claude Code using [TwelveLabs](https://www.twelvelabs.io/) multimodal AI.\n\n## Install\n\n1. Set your TwelveLabs API key as an environment variable (get one at [twelvelabs.io](https://www.twelvelabs.io/)):\n\n```bash\nexport TWELVELABS_API_KEY=your_api_key_here\n```\n\nAdd this to your `~/.zshrc` or `~/.bashrc` to persist it.\n\n2. In Claude Code, add the plugin marketplace:\n\n```\n/plugin marketplace add twelvelabs-io/twelve-labs-claude-code-plugin\n```\n\n3. Then install the plugin:\n\n```\n/plugin install twelvelabs@twelvelabs-plugins\n```\n\nYou may need to restart Claude Code after installing for the plugin and MCP to take effect.\n\nThe plugin configures the MCP server, slash commands, skills, and hooks automatically.\n\n## What You Can Do\n\n**Index videos** from local files, remote URLs, or Google Drive links. Once a video is indexed, it becomes searchable and analyzable. Indexing is asynchronous — you can check on progress at any time.\n\n**Search across your videos** using natural language descriptions of what you're looking for — visual elements, actions, sounds, or on-screen text. You can also search using a reference image to find visually similar content, combine an image with text for refined results, or search for specific people and objects using entity recognition.\n\n**Analyze video content** to generate summaries, extract key topics, answer questions, list action items, or perform any open-ended analysis guided by a custom prompt. Both analyze commands accept indexed `videoId`s, direct URLs, asset IDs, or local files (auto-uploaded as assets). Two modes:\n\n- `/twelvelabs:sync-analyze` — returns the result inline. Pegasus 1.5 by default for URL/asset/file inputs; falls back to Pegasus 1.2 only when analysing an existing indexed `videoId` or when the user explicitly requests 1.2. Cap: ≤1 hour video.\n- `/twelvelabs:async-analyze` — fire-and-forget for longer videos (up to 2 hours), Pegasus 1.5 throughout. Also supports **time-based metadata extraction** (`analysisMode: \"time_based_metadata\"` + `segmentDefinitions`) for per-segment structured output, multimodal prompting with reference images (`promptV2`), and structured JSON output (`jsonSchema`).\n\n**Create video embeddings** for use in downstream applications like similarity search, clustering, or recommendation systems.\n\n**Manage indexes** to organize your videos into separate collections. Each index can be configured with different model capabilities — Marengo for search or Pegasus for text generation.\n\n**Set up entity search** by creating collections of people or objects with reference images. Once configured, you can find exactly when and where a specific person appears across all your indexed videos.\n\n## Usage\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `/twelvelabs:index-video <path-or-url> [index-id]` | Index a local video, URL, or Google Drive link |\n| `/twelvelabs:index-video status [task-id]` | Check indexing task status |\n| `/twelvelabs:indexes` | List all indexes |\n| `/twelvelabs:indexes create <name> [model]` | Create a new index (models: `marengo`, `pegasus`, or both) |\n| `/twelvelabs:indexes delete <index-id>` | Delete an index |\n| `/twelvelabs:videos [index-id]` | List indexed videos |\n| `/twelvelabs:search <query> [index-id]` | Text search across videos |\n| `/twelvelabs:search <image> [text] [index-id]` | Image or composed (image + text) search |\n| `/twelvelabs:search <@entity_id> [action] [index-id]` | Entity search for specific people/objects |\n| `/twelvelabs:sync-analyze <video-id-or-url-or-asset-or-path> [prompt]` | Synchronous analysis. Pegasus 1.5 by default; Pegasus 1.2 forced for `videoId` |\n| `/twelvelabs:async-analyze <url-or-path-or-asset> [prompt]` | Async analysis (Pegasus 1.5, ≤2 hours; supports time-based metadata, `promptV2`, `jsonSchema`) |\n| `/twelvelabs:async-analyze status [task-id]` | Check async-analyze task status |\n| `/twelvelabs:async-analyze list` | List async-analyze tasks |\n| `/twelvelabs:async-analyze delete <task-id>` | Delete an async-analyze task |\n| `/twelvelabs:embed <path-or-url>` | Create video embeddings |\n| `/twelvelabs:embed status [task-id]` | Check embedding task status |\n| `/twelvelabs:entities create-collection <name>` | Create an entity collection |\n| `/twelvelabs:entities list-collections` | List all entity collections |\n| `/twelvelabs:entities create-entity <collection-id> <name> <asset-ids...>` | Create an entity from image asset IDs |\n| `/twelvelabs:entities list-entities <collection-id>` | List entities in a collection |\n| `/twelvelabs:entities delete-entity <collection-id> <entity-id>` | Delete an entity |\n| `/twelvelabs:entities delete-collection <collection-id>` | Delete a collection and all its entities |\n| `/twelvelabs:assets upload <path-or-url>` | Upload a local file or URL as an asset (image or video) |\n| `/twelvelabs:assets delete <asset-id>` | Delete an asset |\n| `/twelvelabs:help` | Show help and available commands |\n\n### Natural Language\n\nYou can also skip slash commands and just describe what you want:\n\n#### Indexing\n\n- \"Index this video: /path/to/video.mp4\"\n- \"Index this URL: https://example.com/video.mp4\"\n- \"Index every video in /path/to/my-videos/\" (batch — folder indexing)\n- \"Index this file and tag it with `project=demo`\" (userMetadata round-trips into search results)\n- \"Add this video for analysis\"\n- \"Process this video file\"\n- \"Add this Google Drive folder for analysis: https://drive.google.com/drive/folders/ABC123\"\n\n#### Checking Status\n\n- \"Is my video ready?\"\n- \"How long until indexing is done?\"\n- \"Is it still processing?\"\n- \"Can I search my video yet?\"\n- \"Check status of task abc123\"\n\n#### Text Search\n\n- \"Find the part where someone is cooking\"\n- \"Search for a red car driving fast\"\n- \"When does the presenter mention AI?\"\n- \"Look for the sunset scene\"\n- \"Find text showing 'hello world'\"\n\n#### Image Search\n\n- \"Find scenes matching this image: https://example.com/photo.jpg\"\n- \"Search with this picture: /path/to/screenshot.png\"\n- \"Find videos that look like this image\"\n\n#### Composed Search (Image + Text)\n\n- \"Find this car but in blue: https://example.com/car.jpg\"\n- \"Find this building at night: https://example.com/building.jpg\"\n- \"Search for this product in premium packaging: /path/to/product.jpg\"\n\n#### Entity Search\n\n- \"Find all clips of Sarah in my videos\"\n- \"I want to track this person across my videos. Here's their photo: https://example.com/sarah.jpg\"\n- \"Set up entity search for Sarah using this photo\"\n- \"Find this person giving a presentation\"\n\n#### Analysis (sync — short videos, returns inline)\n\n- \"What is this video about?\"\n- \"Summarize the key points of this video\"\n- \"Analyze https://example.com/clip.mp4 and tell me what happens\" (URL input — Pegasus 1.5)\n- \"Analyze /path/to/clip.mp4 in one sentence\" (local file — auto-uploaded, Pegasus 1.5)\n- \"Extract action items from this meeting\"\n- \"Return JSON with `{product, timestamp_sec}[]` for every product mentioned\" (structured output via `jsonSchema`)\n\n#### Analysis (async — long videos, segmentation, structured outputs)\n\n- \"Analyze this 90-minute keynote and tell me the key takeaways\"\n- \"Analyze this URL without indexing: https://example.com/long-video.mp4\"\n- \"Extract every highlight from this video with a description and importance score for each\" (time-based metadata extraction)\n- \"Find every shot that looks like this product image\" (multimodal `promptV2` with reference images)\n- \"Is my async analyze task done?\"\n- \"Show all my failed async tasks\"\n- \"Delete the analyze task for that long video\"\n\n#### Embeddings\n\n- \"Create embeddings for this video: /path/to/video.mp4\"\n- \"Embed this video: https://example.com/video.mp4\"\n- \"Are my embeddings ready?\"\n- \"Check embedding status\"\n- \"Get embeddings for video abc123\"\n\n#### Managing Videos & Indexes\n\n- \"What videos do I have?\"\n- \"Show my videos\"\n- \"Do I have any videos indexed?\"\n- \"Which videos can I search?\"\n- \"I need the video ID for my demo\"\n- \"Show my indexes\"\n- \"What indexes do I have?\"\n- \"Create a new index called marketing-videos\"\n- \"Create a search-only index with marengo\"\n\n#### Entity Management\n\n- \"Create an entity collection called My Team\"\n- \"Create an entity for Sarah using these reference image asset IDs\"\n- \"List my entity collections\"\n- \"What entities are in this collection?\"\n- \"Delete this entity\"\n\n#### Assets\n\n- \"Upload this photo as an asset: ./sarah.jpg\"\n- \"Upload this video as an asset: ./keynote.mp4\"\n- \"Upload this image URL as an asset\"\n- \"Delete this asset\"\n\n#### Sample Videos\n\n- \"I don't have a video to test\"\n- \"Show me sample videos\"\n- \"Can I try with a demo video?\"\n\n## Troubleshooting\n\n### \"Video too short\" error\n\nTwelveLabs requires videos to be at least **4 seconds** long.\n\n### Indexing stuck in \"Pending\" or \"Queued\"\n\nVideo indexing can take several minutes depending on video length. Use `/twelvelabs:index-video status` to monitor progress.\n\n### \"Video format not supported\"\n\nSupported formats: MP4, MOV, AVI, MKV, WebM. Convert with:\n```bash\nffmpeg -i input.video -c copy output.mp4\n```\n\n### Search returns no results\n\n- Ensure the video is fully indexed (status: Ready)\n- Try broader or different search terms\n- Verify you're searching in the correct index\n\n### Analysis fails\n\n- Verify the video ID with `/twelvelabs:videos`\n- Ensure the video is fully indexed\n\n## Development\n\n### Load from a local directory (session-only)\n\n```bash\nclaude --plugin-dir path/to/twelve-labs-claude-code-plugin\n```\n\n### Point the marketplace to a local directory\n\n```\n/plugin marketplace add path/to/twelve-labs-claude-code-plugin\n/plugin install twelvelabs@twelvelabs-plugins\n```\n\n## Links\n\n- [TwelveLabs Documentation](https://docs.twelvelabs.io/)\n- [TwelveLabs API Reference](https://docs.twelvelabs.io/reference/api-reference)\n- [TwelveLabs Playground](https://playground.twelvelabs.io/)\n- [TwelveLabs MCP Server (npm)](https://www.npmjs.com/package/twelvelabs-mcp)\n",
  "bytes": 9974,
  "sha": "fda121af18b4e5d765976b2ebed96fb8962504b2f85875ed1a4af91b03bedd49",
  "repo_slug": "twelvelabs-io/twelve-labs-claude-code-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_twelvelabs_io_twelve_labs_claude_code_pl_639759f2/readme"
}