AI Coding Agent Widget for Web Development - Code mutates like cosmic radiation
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
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 • Vite • Next.js • Configuration
Quick Start
1. Install
pip install cosmux
2. Set your API key
# .env or environment
ANTHROPIC_API_KEY=sk-ant-api03-...
3. Start the server
cosmux serve
4. Open the chat
Visit http://localhost:3333/cosmux — the AI assistant is ready!
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 Integration
Inject the widget automatically into your Vite app.
1. Install both packages
pip install cosmux
npm install -D cosmux
2. Add the plugin
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { cosmux } from 'cosmux/vite'
export default defineConfig({
plugins: [
react(),
cosmux() // Starts server + injects widget
]
})
3. Run your dev server
npm run dev
The widget appears automatically! The plugin:
- Starts
cosmux servewhen Vite starts - Injects the widget into your HTML
- Stops the server when Vite closes
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)
})
Next.js Integration
Option 1: Config Wrapper
// next.config.mjs
import { withCosmux } from 'cosmux/next'
export default withCosmux({
// your existing Next.js config
})
Option 2: Widget Component (App Router)
Create a client 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/cosmux-widget.iife.js`
script.async = true
document.body.appendChild(script)
return () => { script.remove() }
}, [port])
return null
}
Add to your layout:
// app/layout.tsx
import { CosmuxWidget } from '@/components/CosmuxWidget'
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<CosmuxWidget />
</body>
</html>
)
}
Manual Integration
For any web project, add the script tags:
<script>
window.__COSMUX_CONFIG__ = { serverUrl: 'http://localhost:3333' };
</script>
<script src="http://localhost:3333/static/cosmux-widget.iife.js"></script>
<link rel="stylesheet" href="http://localhost:3333/static/cosmux-widget.css">
Then start the server:
cosmux serve
CLI Commands
cosmux serve # Start the server
cosmux serve --port 4000 # Custom port
cosmux serve --workspace ./project # Specific workspace
cosmux init # Create CLAUDE.md template
cosmux login # Login with Claude Max (OAuth)
cosmux logout # Remove stored credentials
cosmux status # Show auth status
cosmux version # Show version
Configuration
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
How It Works
- Install —
pip install cosmuxadds the CLI and server - Start —
cosmux serveruns the agent server - Connect — Open
/cosmuxor inject the widget - 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 Starting" in terminal)
- Verify your API key is set in
.env - Try opening
http://localhost:3333/cosmuxdirectly
Server won't start?
- Check if port 3333 is in use:
lsof -i :3333 - Try a different port:
cosmux serve --port 4000
"cosmux: command not found"?
- Make sure Python bin directory is in your PATH
- Try:
python -m cosmux serve
Requirements
- Python 3.11+ — for the server
- Node.js 18+ — only for Vite/Next.js integration (optional)
- Anthropic API key — console.anthropic.com
License
MIT — see LICENSE
Project details
Verified details
These details have been verified by PyPIProject links
GitHub Statistics
Maintainers
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
cosmux-0.2.2.tar.gz
(1.3 MB
view details)
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.2.2.tar.gz.
File metadata
- Download URL: cosmux-0.2.2.tar.gz
- Upload date:
- Size: 1.3 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
af785e7af273df029d6ff0308bc7ca36d0823469b48fcc189550329be009047a
|
|
| MD5 |
d8cfefa92fc60aba7e913c262d0b5de9
|
|
| BLAKE2b-256 |
d564d4118e2df507ecbead8a385ef4620f4da621459f8adb3256299044d199fb
|
Provenance
The following attestation bundles were made for cosmux-0.2.2.tar.gz:
Publisher:
release.yml on techdivision-rnd/cosmux
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cosmux-0.2.2.tar.gz -
Subject digest:
af785e7af273df029d6ff0308bc7ca36d0823469b48fcc189550329be009047a - Sigstore transparency entry: 834711664
- Sigstore integration time:
-
Permalink:
techdivision-rnd/cosmux@92314c0f4eb554bee77ba7b8e27aafa47b96e7f1 -
Branch / Tag:
refs/heads/master - Owner: https://github.com/techdivision-rnd
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@92314c0f4eb554bee77ba7b8e27aafa47b96e7f1 -
Trigger Event:
push
-
Statement type:
File details
Details for the file cosmux-0.2.2-py3-none-any.whl.
File metadata
- Download URL: cosmux-0.2.2-py3-none-any.whl
- Upload date:
- Size: 1.3 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
02eb8d0f4dae24107053cfefe79b063c7228592bbbe6f81662c1c8c3d087f90b
|
|
| MD5 |
32804b083fa91d2d82af1309e43e296c
|
|
| BLAKE2b-256 |
5c1c08c8761be865e29f8f9c2f320b6f98956316f768830c7f3fab0c4f88f5f4
|
Provenance
The following attestation bundles were made for cosmux-0.2.2-py3-none-any.whl:
Publisher:
release.yml on techdivision-rnd/cosmux
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
cosmux-0.2.2-py3-none-any.whl -
Subject digest:
02eb8d0f4dae24107053cfefe79b063c7228592bbbe6f81662c1c8c3d087f90b - Sigstore transparency entry: 834711670
- Sigstore integration time:
-
Permalink:
techdivision-rnd/cosmux@92314c0f4eb554bee77ba7b8e27aafa47b96e7f1 -
Branch / Tag:
refs/heads/master - Owner: https://github.com/techdivision-rnd
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@92314c0f4eb554bee77ba7b8e27aafa47b96e7f1 -
Trigger Event:
push
-
Statement type:
