AI Coding Agent Widget for Web Development - Code mutates like cosmic radiation
Project description
AI coding assistant that lives in your dev environment
Powered by Claude. Reads, writes, and edits your code while you work.
Quick Start • Features • Configuration • How It Works
Quick Start
npm install -D cosmux
// vite.config.ts
import { cosmux } from 'cosmux/vite'
export default defineConfig({
plugins: [cosmux()]
})
# .env
ANTHROPIC_API_KEY=sk-ant-api03-...
Run npm run dev — the widget appears in the bottom-right corner.
Features
| Feature | Description | |
|---|---|---|
| 💬 | Chat Interface | Natural conversation with streaming responses |
| 🧠 | Extended Thinking | Watch the AI reason through complex problems |
| 📁 | File Operations | Read, Write, Edit files in your project |
| 💻 | Terminal Access | Run shell commands via Bash tool |
| 🔍 | Code Search | Glob and Grep tools for finding code |
| 💾 | Session Persistence | Chat history saved locally |
| 📖 | Context-Aware | Reads CLAUDE.md for project understanding |
Vite Setup
Works with React, Vue, Svelte, and other Vite-based projects.
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { cosmux } from 'cosmux/vite'
export default defineConfig({
plugins: [
react(),
cosmux()
]
})
The plugin automatically starts the Cosmux server and injects the widget.
Next.js Setup
// next.config.mjs
import { withCosmux } from 'cosmux/next'
export default withCosmux({
// your existing Next.js config
})
For App Router, create a widget component:
// components/CosmuxWidget.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
}
// app/layout.tsx
import { CosmuxWidget } from '@/components/CosmuxWidget'
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<CosmuxWidget />
</body>
</html>
)
}
Configuration
Plugin Options
cosmux({
port: 3333, // Server port (default: 3333)
autoStart: true, // Auto-start server (default: true)
injectWidget: true, // Inject widget script (default: true)
workspace: './', // Workspace path (default: cwd)
})
Environment Variables
| Variable | Description | Default |
|---|---|---|
ANTHROPIC_API_KEY |
Your Anthropic API key | Required |
COSMUX_PORT |
Server port | 3333 |
COSMUX_MODEL |
Claude model | claude-opus-4-5-20251101 |
Project Context
Create a CLAUDE.md file in your project root to give the AI context:
# My Project
## Tech Stack
- React 18 + TypeScript
- Tailwind CSS
## Code Style
- Use functional components
- Prefer named exports
CLI
Run Cosmux standalone:
npx cosmux serve # Start server
npx cosmux serve --port 4000 # Custom port
npx cosmux serve --workspace ./project # Specific workspace
Manual Integration
For projects without Vite or Next.js:
<script>
window.__COSMUX_CONFIG__ = { serverUrl: 'http://localhost:3333' };
</script>
<script src="http://localhost:3333/static/inject.js"></script>
npx cosmux serve
How It Works
- Install — Downloads a platform-specific binary
- Configure — Plugin starts the server automatically
- Develop — Widget injects into your dev HTML
- Code — AI reads and modifies files in your workspace
All file operations happen locally. Your code is only sent to Claude's API for processing.
Troubleshooting
Widget doesn't appear?
- Check that the server is running (look for "Cosmux server ready" in terminal)
- Verify your API key is set in
.env - Try opening
http://localhost:3333/widgetdirectly
Server won't start?
- Check if port 3333 is in use:
lsof -i :3333 - Try a different port:
cosmux({ port: 4000 })
Binary download failed?
- Install via pip as fallback:
pip install cosmux
Requirements
- Node.js 18+
- Anthropic API key — console.anthropic.com
License
MIT — see LICENSE
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file cosmux-0.1.0.tar.gz.
File metadata
- Download URL: cosmux-0.1.0.tar.gz
- Upload date:
- Size: 1.3 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
570e80993380ccdc59d4c3b84699f8d1887daba16eaef9d95f351b7de5bffa5d
|
|
| MD5 |
702724e42ecb7d1fd47b76db150047df
|
|
| BLAKE2b-256 |
af01a4e5bb56ea96aa1ab6f047510a228c379740d163d12b72b1ae3a59161e20
|
File details
Details for the file cosmux-0.1.0-py3-none-any.whl.
File metadata
- Download URL: cosmux-0.1.0-py3-none-any.whl
- Upload date:
- Size: 1.3 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.8
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3480d7f9395b20327afd0153d5c30cbcaf3145ae7d94f8551a477f0404e0b65d
|
|
| MD5 |
4c06c228eb8dfaab64c19aeb67be3477
|
|
| BLAKE2b-256 |
c2425fd371c5b68bb85d07c9810635ae9f2b6ad8928be69bbfd72062ffbf66fc
|
