# Install the Framia Plugin in Claude

This guide covers setting up the Framia Plugin across **Claude Desktop** (`Chat`, `Cowork`, and `Code` tabs) and **Claude Code CLI** from the [official download page](https://mcp.framia.pro/downloads/).

## 1. Choose the right Framia Plugin package

- **`framia-plugin-claude.zip` (`Claude Plugin · Chat, Cowork & Code`)**: Cross-platform package for **macOS**, **Windows**, and **Linux**. It bundles `framia/.claude-plugin/plugin.json`, `framia/.claude-plugin/marketplace.json`, all Framia skills, and the remote HTTP MCP server configuration (`https://mcp-api.framia.pro/multimodal/mcp` with automatic OAuth / CIMD discovery) without any local binary directory. Use this package for **`Chat`**, **`Cowork`**, and **`Code`** tabs or **Claude Code CLI**.
- **Platform-specific local-bridge packages (`framia-plugin-darwin-arm64.zip`, `framia-plugin-linux-amd64.zip`, `framia-plugin-linux-arm64.zip`)**: Bundles the native `framia/bin/framia` local MCP bridge alongside `.codex-plugin/plugin.json` and `.claude-plugin/plugin.json`. Supported in **Codex** and **Claude Code** (`Code` tab or CLI). Do not upload a platform local-bridge ZIP to `Chat` or `Cowork`, because `Chat` and `Cowork` reject archives containing a `bin/` directory.

A successful download does not grant account access or select a workspace.

## 2. Chat & Cowork tabs in Claude Desktop

In the `Chat` and `Cowork` tabs, the user uploads the plugin ZIP through the Claude Desktop interface and connects it in the browser:

1. Download **Claude Plugin · Chat, Cowork & Code** (`framia-plugin-claude.zip`) from [https://mcp.framia.pro/downloads/](https://mcp.framia.pro/downloads/).
2. In Claude Desktop, open **Customize → Plugins → Add → Upload plugin** and select `framia-plugin-claude.zip` directly (do not extract it first).
3. Open the installed **Framia** plugin, switch to its **Connectors** tab, and click **Connect** next to `framia` (if **Connect** asks you to open a `Code` session first, open a new `Code` tab session so it loads the connector, or run `/mcp` in `Code`).
4. In the browser window that opens, sign in to your Framia account and choose your workspace and permissions.
5. Once connected under **Customize → Plugins**, the Framia skills and MCP tools are available in `Chat`, `Cowork`, and desktop `Code` sessions. Continue to section 4 to verify.

## 3. Code tab in Claude Desktop & Claude Code CLI

### Option A: Install `framia-plugin-claude.zip` (Recommended, cross-platform)

If you already uploaded and connected `framia-plugin-claude.zip` under **Customize → Plugins** in Claude Desktop (section 2), it syncs to your desktop sessions automatically.

To install directly in Claude Code (`Code` tab or CLI):

1. Download `framia-plugin-claude.zip` from [https://mcp.framia.pro/downloads/](https://mcp.framia.pro/downloads/) (to automate download in a terminal, read `https://mcp.framia.pro/downloads/stable.json` for the current `version` and fetch `https://mcp.framia.pro/downloads/releases/<version>/framia-plugin-claude.zip`), then extract it into a user-owned directory so `./framia/.claude-plugin/plugin.json` exists.
2. From the directory containing `framia/`, register and install the plugin:

       claude plugin install framia --marketplace ./framia

   (Or load it for a single session with `claude --plugin-dir ./framia`.)
3. Confirm installation with `claude plugin list` and `claude mcp list`. Authenticate the `framia` MCP server when prompted (or via `/mcp` in Claude Code) and choose your workspace and permissions in the browser.

### Option B: Install the platform-matched local-bridge Plugin ZIP

If you prefer the local stdio bridge in Claude Code on **macOS Apple Silicon**, **Linux x64**, or **Linux ARM64**:

1. Download and extract the matching `framia-plugin-<os>-<arch>.zip` from [https://mcp.framia.pro/downloads/](https://mcp.framia.pro/downloads/).
2. From the directory containing `framia/`, sign in before installing:

       ./framia/bin/framia --environment prod auth plugin-login

   Wait for the user to complete sign-in and choose the workspace and permissions in the browser. (In remote/headless Linux sandboxes without localhost port-forwarding, run `./framia/bin/framia --environment prod auth plugin-login --print-auth-url` and finish with `--callback-url '<REDIRECTED_CALLBACK_URL>'`; in managed sandboxes that inject `FRAMIA_API_KEY`, `mcp serve` uses the injected key directly.)
3. Install the extracted folder in Claude Code:

       claude plugin install framia --marketplace ./framia

## 4. Verify in a new session

Start a new session in **Chat**, **Cowork**, or **Code** and run this read-only check:

> Call framia_guide with topic projects, then call framia_projects_list with page 1 and page_size 1. Report whether the real tool calls succeeded and how many projects were returned. Do not create, modify or delete anything, and do not run a generation task. If the tools are unavailable or return an error, report that result without claiming success.

A successful empty project list is valid. Do not use a paid generation task as an installation test.

## Ask Claude to set it up or guide you

Copy this into Claude (`Code`, `Chat`, or `Cowork`) for automated setup or step-by-step guidance:

Read https://mcp.framia.pro/install/claude.md and follow it to set up the Framia Plugin in Claude. If you are running in Claude Code (the Code tab or CLI), download and extract framia-plugin-claude.zip from https://mcp.framia.pro/downloads/ and install it with claude plugin install framia --marketplace ./framia (or use the platform-matched local-bridge Plugin ZIP and run its bundled auth plugin-login). If you are in Chat or Cowork, guide me step by step to upload framia-plugin-claude.zip under Customize → Plugins → Add → Upload plugin and click Connect under Connectors. Wait while I sign in and choose my workspace and permissions in the browser, then verify a read-only project list in a new session.

This Markdown is public guidance, not an installer or an authorization grant. Do not use sudo, pipe a download into a shell, disable TLS, or overwrite unrelated configuration.
