Cosmux AI Widget Setup

Installs and configures Cosmux, an AI coding assistant widget powered by Claude that integrates directly into your local development environment.

What This Skill Does

This skill helps you set up Cosmux in your Vite or Next.js project. Cosmux provides a floating widget in your browser during development that gives you AI-powered coding assistance via Claude. It requires an Anthropic API key or Claude Max subscription.

Instructions

Step 1: Verify Project Type

Check if the project uses Vite or Next.js by looking for:

Step 2: Install Cosmux

Install the package as a dev dependency:

```bash

npm install -D cosmux

```

Step 3: Configure Based on Framework

#### For Vite Projects

1. Open the Vite config file (`vite.config.ts` or `vite.config.js`)

2. Import the Cosmux plugin at the top:

```typescript

import { cosmux } from 'cosmux/vite'

```

3. Add `cosmux()` to the plugins array:

```typescript

export default defineConfig({

plugins: [

// existing plugins...

cosmux()

]

})

```

#### For Next.js Projects

1. Open the Next.js config file (`next.config.mjs`, `next.config.js`, or `next.config.ts`)

2. Import the Cosmux wrapper:

```javascript

import { withCosmux } from 'cosmux/next'

```

3. Wrap the existing config:

```javascript

export default withCosmux({

// existing Next.js config

})

```

4. **For App Router projects only**: Create a client-side widget component:

- Create `components/CosmuxWidget.tsx` (or `.jsx`):

```tsx

'use client'

import { useEffect } from 'react'

export function CosmuxWidget({ port = 3333 }: { port?: number }) {

useEffect(() => {

if (process.env.NODE_ENV !== 'development') return

;(window as any).__COSMUX_CONFIG__ = { serverUrl: `http://localhost:${port}` }

const script = document.createElement('script')

script.src = `http://localhost:${port}/static/inject.js`

script.async = true

document.body.appendChild(script)

return () => { script.remove() }

}, [port])

return null

}

```

5. **For App Router projects only**: Add widget to root layout:

- Open `app/layout.tsx` (or `.jsx`)

- Import the widget: `import { CosmuxWidget } from '@/components/CosmuxWidget'`

- Add `<CosmuxWidget />` before the closing `</body>` tag

Step 4: Set Up Environment Variable

1. Check if `.env` or `.env.local` exists in the project root

2. If it exists, open it; otherwise create `.env`

3. Add the Anthropic API key variable:

```bash

ANTHROPIC_API_KEY=sk-ant-...

```

4. Inform the user they need to add their actual API key (obtain from https://console.anthropic.com/)

Step 5: Verify .gitignore

Ensure `.env` and `.env.local` are in `.gitignore` to prevent committing the API key.

Step 6: Usage Instructions

Inform the user:

1. Run their dev server (`npm run dev`)

2. The Cosmux widget will appear in the bottom-right corner of their browser

3. Press `Cmd+K` (Mac) or `Ctrl+K` (Windows/Linux) to activate the AI assistant

4. Alternatively, click the widget button to open

Configuration Options

Both Vite and Next.js plugins accept optional configuration:

Example with custom port:

```typescript

cosmux({ port: 4000 })

```

Alternative: CLI Mode

Users can also run Cosmux via CLI without framework integration:

```bash

npx cosmux serve

npx cosmux serve --port 4000

```

Requirements

Troubleshooting

Notes