cosmux

AI Coding Agent Widget for Web Development - Code mutates like cosmic radiation

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

zelgerj

These details have not been verified by PyPI

Project description

Cosmux

AI coding assistant that lives in your dev environment
Powered by Claude. Reads, writes, and edits your code while you work.

Cosmux Workflow

Quick Start • Features • Vite • Next.js • Configuration

Choose Your Integration

Your Project	Recommended
Plain HTML/CSS	`cosmux dev` — zero config!
Vite/React/Vue	Vite Plugin
Next.js	Next.js Wrapper
Other frameworks	Manual Script
Standalone Chat	`http://localhost:3333/cosmux`

HTML/CSS Projects

The simplest way to use Cosmux. No configuration needed.

1. Install

pip install cosmux

2. Set your API key

export ANTHROPIC_API_KEY=sk-ant-api03-...

3. Start development

cd your-website/
cosmux dev

Open http://localhost:5174 — your website with the AI assistant injected.

What you get:

CSS changes update instantly (no page reload)
HTML changes auto-reload the page
Widget auto-injected into your HTML
Backend + Vite dev server managed for you

Quick Start (Standalone)

Just want the chat interface? No widget injection needed.

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 serve when 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 tag:

<script>
  window.__COSMUX_CONFIG__ = { serverUrl: 'http://localhost:3333' };
</script>
<script src="http://localhost:3333/static/cosmux-widget.iife.js"></script>

Note: CSS is automatically included via Shadow DOM — no separate stylesheet needed.

Then start the server:

cosmux serve

CLI Commands

# Development (HTML/CSS projects)
cosmux dev                          # Start dev environment with HMR
cosmux dev --port 8080              # Custom dev server port
cosmux dev -w ./my-site             # Specify workspace

# Server only (for other integrations)
cosmux serve                        # Start the backend server
cosmux serve --port 4000            # Custom port
cosmux serve --workspace ./project  # Specific workspace

# Setup & Auth
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 cosmux adds the CLI and server
Start — cosmux serve runs the agent server
Connect — Open /cosmux or 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/cosmux directly

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

Contributing • Issues

Project details

These details have been verified by PyPI

Project links

GitHub Statistics

Maintainers

zelgerj

These details have not been verified by PyPI

Release history Release notifications | RSS feed

0.4.3

Jan 19, 2026

0.4.2

Jan 19, 2026

This version

0.4.1

Jan 19, 2026

0.3.1

Jan 19, 2026

0.3.0

Jan 19, 2026

0.2.2

Jan 19, 2026

0.1.2

Jan 15, 2026

0.1.0

Jan 15, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

cosmux-0.4.1-py3-none-any.whl (1.7 MB view details)

Uploaded Jan 19, 2026 Python 3

File details

Details for the file cosmux-0.4.1-py3-none-any.whl.

File metadata

Download URL: cosmux-0.4.1-py3-none-any.whl
Upload date: Jan 19, 2026
Size: 1.7 MB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for cosmux-0.4.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`875a7a64acf707466bbacd1956cf6515bd880a7f1ed6c8994a3c0f2b46fdcc00`
MD5	`094d91cbe6892895db3d7cb16b8c0fc7`
BLAKE2b-256	`96ac403e4e7a1e229e5b22326200f768317b4df089a90def8d833355929b316d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for cosmux-0.4.1-py3-none-any.whl:

Publisher: release.yml on techdivision-rnd/cosmux

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: cosmux-0.4.1-py3-none-any.whl
- Subject digest: 875a7a64acf707466bbacd1956cf6515bd880a7f1ed6c8994a3c0f2b46fdcc00
- Sigstore transparency entry: 834939741
- Sigstore integration time: Jan 19, 2026
Source repository:
- Permalink: techdivision-rnd/cosmux@3f3ec9c76b0e23d056cf7edfd9dd1f84ff4ca5cb
- Branch / Tag: refs/heads/master
- Owner: https://github.com/techdivision-rnd
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@3f3ec9c76b0e23d056cf7edfd9dd1f84ff4ca5cb
- Trigger Event: push

cosmux 0.4.1

Navigation

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Project description

Choose Your Integration

HTML/CSS Projects

1. Install

2. Set your API key

3. Start development

Quick Start (Standalone)

1. Install

2. Set your API key

3. Start the server

4. Open the chat

Features

Vite Integration

1. Install both packages

2. Add the plugin

3. Run your dev server

Plugin Options

Next.js Integration

Option 1: Config Wrapper

Option 2: Widget Component (App Router)

Manual Integration

CLI Commands

Configuration

Environment Variables

Project Context

How It Works

Troubleshooting

Requirements

License

Project details

Verified details

Project links

GitHub Statistics

Maintainers

Unverified details

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distributions

Built Distribution

File details

File metadata

File hashes

Provenance