ChatCut plugin for Claude Code install guide

This plain text version is returned because this request does not look like a browser page navigation.
Browser page: https://chatcut.io/claude

Full installation guide:

Install the ChatCut-maintained Claude Code plugin from ChatCut's public marketplace, pinned to `main`.

## Install and log in

Run these two install commands first, in order:

```text
claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main
claude plugin install chatcut@chatcut-inc
```

The marketplace command clones a large repository and can take several minutes. Run it as a long-running process with a generous timeout and poll it until it exits. No output for a while does not mean it has failed; do not cancel it merely because an ordinary short command timeout expires.

If this machine may have used ChatCut before, optionally check for a pre-existing standalone MCP server configuration:

```text
claude mcp get chatcut
```

If that command finds a server named exactly `chatcut`, remove the legacy standalone entry before logging in:

```text
claude mcp remove chatcut
```

Do not remove `plugin:chatcut:chatcut`; that is the server managed by the newly installed plugin. If `claude mcp get chatcut` reports that no such server exists, continue normally.

Then log in to the ChatCut MCP server using the plugin's login script.

```text
sh "${CLAUDE_PLUGIN_ROOT}/skills/chatcut-plugin-basics-claude/login-chatcut.sh" > /tmp/chatcut-login.log 2>&1 &
```

Immediately read and poll `/tmp/chatcut-login.log`. Claude Code will open the ChatCut authorization page.

Confirm the installation after authentication:

```text
claude plugin list
claude mcp get plugin:chatcut:chatcut
```

The plugin list must show `chatcut@chatcut-inc` as enabled. The authoritative OAuth success signal is the `Authenticated with "plugin:chatcut:chatcut"` login output, not `Connected` by itself.



Finally, explain that ChatCut supports video editing, motion graphics, and generation of video, voiceover, music, sound effects, and other project assets. Plugin tools load only when a session starts, so tell the user to click **New session** and make a natural-language request that names ChatCut, such as “Use ChatCut to help me...”. Do not attempt a ChatCut tool call in the installation session or prescribe a fixed prompt.

Claude Code shares `~/.claude` between the CLI and desktop app, so the plugin and OAuth session are available to both and the session refreshes automatically.

## Failure-mode debugging

Treat setup as one continuous operation. A half-installed or installed-but-not-authenticated plugin is a failure state: diagnose the matching symptom below, recover, and resume at the interrupted step. Any unavoidable browser, OS password, or installer confirmation is an active wait state, not the end of the task.

### `claude` is missing or too old

The login command requires Claude Code `2.1.210` or newer. Check both capabilities:

```text
claude --version
claude mcp login --help
```

If the current shell cannot resolve `claude`, first check `command -v claude` and `~/.local/bin/claude`. On Windows also resolve it across shells with:

```text
powershell.exe -NoProfile -Command "(Get-Command claude -ErrorAction SilentlyContinue).Source"
cmd.exe /d /c where claude
```

Invoke a resolved executable directly rather than reinstalling because one shell has stale or different `PATH`. Claude Code Desktop alone does not guarantee that the terminal CLI exists.

Only when no terminal executable exists, use Anthropic's official installer:

```text
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
```

If the CLI exists but is too old, do not ask the user which upgrade method to use. Run `claude update` with a generous timeout, then recheck both commands. If it hangs, fails, or leaves `claude mcp login --help` unavailable, run `npm install -g @anthropic-ai/claude-code@latest` and recheck. A native update may need a TTY:

```text
python3 -c 'import pty,sys; pty.spawn(sys.argv[1:])' claude update
```

If an installer requests an OS/admin password, state the exact action once, keep waiting, and resume automatically afterward. Behind a proxy, set the user's actual `HTTPS_PROXY` before retrying.

### Marketplace add is slow

`claude plugin marketplace add` is a long-running clone. Start it with a timeout suitable for a large repository and poll the process rather than repeatedly launching it. Let the current process finish unless it exits with an error or is clearly stalled beyond the generous timeout. Do not run concurrent marketplace-add attempts.

If the process is still alive but quiet, continue waiting. If the execution environment imposes a short timeout, run it in a background/long-running shell with output captured to a log, poll both process state and log, and only retry after the prior process has exited.

### Marketplace add fails on the network

Timeouts, TLS/DNS failures, `fatal: early EOF`, and a misleading `fatal: Invalid path ...` commonly indicate an interrupted GitHub transfer, not a bad repository filename. Retry with backoff while keeping the install active.

Use the user's existing proxy when available. Read `HTTPS_PROXY` and `HTTP_PROXY`, or identify their running proxy tool and actual port; common local ports include `7890`, `7897`, `1080`, `8080`, and `8888`, but do not blindly select one or leave a bad proxy configured.

```text
# macOS / Linux example; substitute the user's actual proxy
HTTPS_PROXY=http://127.0.0.1:7890 ALL_PROXY=http://127.0.0.1:7890 claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main

# Windows PowerShell example
$env:HTTPS_PROXY='http://127.0.0.1:7890'; $env:ALL_PROXY=$env:HTTPS_PROXY; claude plugin marketplace add https://github.com/ChatCut-Inc/agent-plugin.git#main
```

If the full marketplace clone repeatedly drops, make a shallow clone as another long-running process, poll it to completion, then add the local path and install:

```text
git clone --depth 1 --branch main https://github.com/ChatCut-Inc/agent-plugin.git
claude plugin marketplace add /path/to/agent-plugin
claude plugin install chatcut@chatcut-inc
```

If marketplace add reports `program not found`, confirm `git --version`. Install Git non-interactively where possible with `brew install git`, `winget install Git.Git`, `apt-get install -y git`, or `dnf install -y git`, ensure it is on `PATH`, and retry. Wait through any unavoidable OS installer confirmation.

### Login says stdin is not a terminal

The plugin login script starts its own PTY. Run it from the happy path instead of invoking `claude mcp login` directly.

If direct login is required and `python3` is unavailable, use the platform-specific `script` syntax:

```text
# macOS (BSD script)
script -q /tmp/chatcut-login.log claude mcp login plugin:chatcut:chatcut &

# Linux (util-linux script)
script -qc "claude mcp login plugin:chatcut:chatcut" /tmp/chatcut-login.log &
```

Do not copy one OS's `script` form to the other.

On Windows, first make a best-effort attempt to run the PTY-wrapped login command from a shell with `python3` available:

```text
python3 -c 'import pty,sys; pty.spawn(sys.argv[1:])' claude mcp login plugin:chatcut:chatcut > /tmp/chatcut-login.log 2>&1 &
```

If that shell cannot run `python3` or the command, confirm `cmd.exe /d /c where claude`, then use a throwaway real console while capturing output:

```text
Start-Process cmd -ArgumentList '/c','claude mcp login plugin:chatcut:chatcut > %TEMP%\chatcut-login.log 2>&1'
```

The console may be blank because output is redirected. Poll `$env:TEMP\chatcut-login.log`; open the clean authorization URL as soon as it appears and keep polling.

### A legacy ChatCut MCP server conflicts with the plugin

Use `claude mcp list` to distinguish a standalone server named `chatcut` from the plugin-managed server named `plugin:chatcut:chatcut`. Remove only the standalone entry with `claude mcp remove chatcut`, then verify that `claude mcp get plugin:chatcut:chatcut` still resolves. Never remove the namespaced plugin server as cleanup.

### Login times out or returns a 5xx

If login prints `Authentication timeout`, immediately run logout, start one fresh login process, show the fresh authorization URL, and resume polling. Never run concurrent login attempts.

Before authentication succeeds, HTTP 502 and other 5xx responses during OAuth discovery, registration, callback handling, or token exchange are retryable service failures, not bad credentials and not a reason to reinstall. Wait for the current login process to exit, retry with backoff, and optionally probe availability:

```text
curl -fsS https://api.chatcut.io/.well-known/oauth-authorization-server
```

Use `curl.exe` on Windows. A successful discovery response only proves that endpoint is reachable; continue until the login process prints the authenticated line.

### `claude mcp login` does not exist

Upgrade Claude Code using the earlier recovery steps. The pseudo-terminal wrappers solve non-interactive-shell errors, so an old CLI is the only reason to use an app-UI fallback.

Only after capturing exact evidence that both upgrade routes failed, tell the user to type `/mcp`, select `chatcut` (`plugin:chatcut:chatcut`), and choose **Authenticate**. Keep polling `claude mcp get plugin:chatcut:chatcut` and resume automatically when authentication becomes available.

### Verification is confusing or tools are slow

`claude mcp get` can report `Connected` before OAuth succeeds. `Needs authentication` before a successful login means return to the login loop. `Connected · tools fetch failed` or `Request timed out` is commonly a transient slow backend; do not reinstall or stop over it.

After the login output has already confirmed authentication, a slow tool-list fetch can briefly flip status to `Needs authentication`, and initial calls in the new session can time out while the backend warms. Retry the load or call; do not re-run login. Treat it as a real authentication problem only if a ChatCut tool repeatedly returns an explicit `connector authentication is missing` error rather than a timeout.

## Update failure recovery

The normal refresh commands are:

```text
claude plugin marketplace update chatcut-inc
claude plugin update chatcut@chatcut-inc
```

If an update fails, apply the matching CLI, long-running marketplace, network, or proxy recovery above, then rerun verification. Refreshed tools also load only in a **new session**; do not run or ask the user to run `/reload-plugins`.