twelvelabs

TwelveLabs Claude Code Plugin

Index, search, and analyze videos directly from Claude Code using TwelveLabs multimodal AI.

Install

1. Set your TwelveLabs API key as an environment variable (get one at twelvelabs.io):

export TWELVELABS_API_KEY=your_api_key_here

Add this to your ~/.zshrc or ~/.bashrc to persist it.

2. In Claude Code, add the plugin marketplace:

/plugin marketplace add twelvelabs-io/twelve-labs-claude-code-plugin

3. Then install the plugin:

/plugin install twelvelabs@twelvelabs-plugins

You may need to restart Claude Code after installing for the plugin and MCP to take effect.

The plugin configures the MCP server, slash commands, skills, and hooks automatically.

What You Can Do

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.

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.

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 videoIds, direct URLs, asset IDs, or local files (auto-uploaded as assets). Two modes:

• /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.
• /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).

Create video embeddings for use in downstream applications like similarity search, clustering, or recommendation systems.

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.

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.

Usage

Commands

Command	Description
/twelvelabs:index-video <path-or-url> [index-id]	Index a local video, URL, or Google Drive link
/twelvelabs:index-video status [task-id]	Check indexing task status
/twelvelabs:indexes	List all indexes
/twelvelabs:indexes create <name> [model]	Create a new index (models: marengo, pegasus, or both)
/twelvelabs:indexes delete <index-id>	Delete an index
/twelvelabs:videos [index-id]	List indexed videos
/twelvelabs:search <query> [index-id]	Text search across videos
/twelvelabs:search <image> [text] [index-id]	Image or composed (image + text) search
/twelvelabs:search <@entity_id> [action] [index-id]	Entity search for specific people/objects
/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
/twelvelabs:async-analyze <url-or-path-or-asset> [prompt]	Async analysis (Pegasus 1.5, ≤2 hours; supports time-based metadata, promptV2, jsonSchema)
/twelvelabs:async-analyze status [task-id]	Check async-analyze task status
/twelvelabs:async-analyze list	List async-analyze tasks
/twelvelabs:async-analyze delete <task-id>	Delete an async-analyze task
/twelvelabs:embed <path-or-url>	Create video embeddings
/twelvelabs:embed status [task-id]	Check embedding task status
/twelvelabs:entities create-collection <name>	Create an entity collection
/twelvelabs:entities list-collections	List all entity collections
/twelvelabs:entities create-entity <collection-id> <name> <asset-ids...>	Create an entity from image asset IDs
/twelvelabs:entities list-entities <collection-id>	List entities in a collection
/twelvelabs:entities delete-entity <collection-id> <entity-id>	Delete an entity
/twelvelabs:entities delete-collection <collection-id>	Delete a collection and all its entities
/twelvelabs:assets upload <path-or-url>	Upload a local file or URL as an asset (image or video)
/twelvelabs:assets delete <asset-id>	Delete an asset