# How to Integrate Claude Video with Claude Code vs Codex and Cursor: A Complete Guide

> Integrate Claude Video across Claude Code, Codex, and Cursor seamlessly. This guide details native plugin and npm CLI setups for unified runtime behavior. Get started today.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-11

---

**Claude Video is a self-contained Agent Skill that installs via native plugin commands on Claude Code and the npm CLI on Codex/Cursor, sharing identical runtime behavior across all platforms after a unified first-run setup.**

Claude Video (bradautomates/claude-video) brings video analysis capabilities to AI coding assistants through a portable Agent Skill architecture. Whether you are using Claude Code or alternatives like Codex and Cursor, you can integrate the same `/watch` functionality using platform-specific installation commands while leveraging identical underlying scripts.

## Claude Code Integration Workflow

### Adding the Marketplace and Installing the Skill

To integrate Claude Video with Claude Code, you first register the marketplace repository and install the watch skill. Run these commands in your Claude Code session:

```text
/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video

```

When you execute `/plugin install`, the plugin manager copies the entire `skills/watch/` folder into the Claude Code plugin cache at `~/.claude/plugins/cache/claude-video/watch/...`. The host reads [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) to determine the entry point and resolve `SKILL_DIR` to the absolute path of the installed folder.

### First-Run Setup and Configuration

Before the first `/watch` invocation, the skill automatically executes `scripts/setup.py --check`. This script verifies that `ffmpeg`, `yt-dlp`, and a Whisper API key are present. If any dependencies are missing, it scaffolds `~/.config/watch/.env` and guides you through installation. This pre-flight check runs only once; subsequent calls execute silently.

### Using the /watch Command

After installation, invoke the skill directly:

```text
/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?

```

The entry point [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) orchestrates the workflow: downloading the required segment, extracting frames with [`scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/frames.py), generating transcripts via [`scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/whisper.py) or Groq, and returning the analysis.

## Codex and Cursor Integration Workflow

### Installing via the Agent Skills CLI

Codex and Cursor utilize the generic Agent Skills CLI rather than Claude Code's native plugin system. Install the skill globally using npm:

```bash
npx skills add bradautomates/claude-video -g

```

The `-g` flag copies the complete `skills/watch/` directory—including [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and the `scripts/` subfolder—into the host's skill directory (typically `~/.codex/skills/watch`). Because the skill is self-contained, no additional file manipulation is required.

### Cross-Platform First-Run Setup

Regardless of the host, the same `scripts/setup.py --check` executes on the first `/watch` invocation. It creates `~/.config/watch/.env` and installs missing binaries exactly as it does on Claude Code, ensuring consistent environment preparation across platforms.

### Invoking the Skill

Inside Codex or Cursor chat, use the identical slash command:

```text
/watch https://youtu.be/dQw4w9WgXcQ summarize this video

```

The host resolves [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), locates [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py), and executes it using the same harness-agnostic path resolution logic that works on Claude Code.

## Architectural Consistency Across Platforms

### Self-Contained Skill Design

The skill resides entirely within `skills/watch/`, containing both the contract ([`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md)) and runtime scripts (`scripts/`). This containment ensures that copying the folder to any host—whether Claude Code's cache or Codex's skill directory—preserves all functionality without path breakage.

### Harness-Agnostic Path Resolution

Unlike skills that rely on host-specific environment variables like `CLAUDE_SKILL_DIR`, Claude Video computes `SKILL_DIR` dynamically from the location of the currently read [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file. As defined in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) (lines 20-27), the scripts determine their base directory relative to the contract file, enabling portable execution.

### Idempotent Setup Preflight

The [`scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/setup.py) script runs identically on every host, checking for `ffmpeg`, `yt-dlp`, and API keys before the main logic executes. This guarantees that platform differences stop at the installation boundary; runtime behavior remains consistent.

## Key Source Files and Components

- **Skill Contract ([`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md))**: Defines the slash command, version, and entry point. Lines 20-27 specify the path resolution logic that sets `SKILL_DIR`.

- **Entry Point ([`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py))**: Orchestrates the video processing pipeline from download to transcription.

- **Helper Scripts (`skills/watch/scripts/`)**: Includes [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py), [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py), [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py), [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py), and [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) for modular functionality.

- **Installation Metadata**: [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json) and [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json) inform each host of the skill version and location.

- **Build Script ([`skills/watch/scripts/build-skill.sh`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh))**: Creates `.skill` bundles for `claude.ai` uploads.

## Practical Code Examples

**Claude Code (Plugin Commands)**

```text
/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video
/watch https://youtu.be/dQw4w9WgXcQ what happens at 30s?

```

**Codex / Cursor (NPM CLI)**

```bash
npx skills add bradautomates/claude-video -g

```

```text
/watch https://youtu.be/dQw4w9WgXcQ summarize this video

```

**Direct Script Invocation (Debugging)**

For local debugging without the slash command infrastructure:

```bash
SKILL_DIR=$(pwd)/skills/watch
python3 "$SKILL_DIR/scripts/watch.py" "https://youtu.be/dQw4w9WgXcQ" --detail efficient

```

## Summary

- **Claude Video** installs as a self-contained Agent Skill in `skills/watch/` that works identically across Claude Code, Codex, and Cursor.
- **Claude Code** users install via `/plugin marketplace add` and `/plugin install`, while **Codex/Cursor** users use `npx skills add -g`.
- The **first-run setup** (`scripts/setup.py --check`) runs automatically on any host to configure `~/.config/watch/.env` and verify dependencies.
- **Path resolution** is harness-agnostic; `SKILL_DIR` derives from [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) location, eliminating host-specific environment variable dependencies.
- All platforms invoke the same `/watch` command backed by [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py) and helper modules in `skills/watch/scripts/`.

## Frequently Asked Questions

### Do I need to modify the skill code to use it with Codex instead of Claude Code?

No. The skill is intentionally host-agnostic. The same `skills/watch/` folder containing [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and the `scripts/` directory functions on both platforms without modification. Only the installation command differs between Claude Code's plugin system and Codex's npm CLI.

### Where does the skill store its configuration and API keys?

The first-run setup creates `~/.config/watch/.env` regardless of the host platform. This file stores your Whisper API key and other configuration parameters. The setup script at [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) scaffolds this location automatically if it does not exist.

### Can I run the video processing scripts manually without the slash command?

Yes. You can invoke [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py) directly by setting the `SKILL_DIR` environment variable to the path containing [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md). For example: `SKILL_DIR=$(pwd)/skills/watch python3 $SKILL_DIR/scripts/watch.py "URL"`. This is useful for debugging or automated pipelines outside of chat interfaces.

### What dependencies are required for the first-run setup?

The `scripts/setup.py --check` verification ensures that `ffmpeg`, `yt-dlp`, and a valid Whisper API key (or Groq configuration) are present. If any component is missing, the script halts execution and provides installation instructions before creating `~/.config/watch/.env`.