cmux 0.2.39 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/AGENTS.md +87 -0
  2. package/README.md +48 -28
  3. package/bin/cmux +97 -0
  4. package/lib/postinstall.js +29 -0
  5. package/llms.txt +70 -0
  6. package/package.json +35 -29
  7. package/cmux-cli +0 -0
package/AGENTS.md ADDED
@@ -0,0 +1,87 @@
1
+ # cmux CLI - Agent Instructions
2
+
3
+ cmux is a CLI for managing cloud development VMs. Use these commands to help users work with remote development environments.
4
+
5
+ ## Quick Reference
6
+
7
+ ```bash
8
+ # Authentication
9
+ cmux login # Login (opens browser)
10
+ cmux logout # Logout
11
+ cmux whoami # Show current user and team
12
+
13
+ # VM Lifecycle
14
+ cmux start [path] # Create VM, optionally sync directory
15
+ cmux ls # List all VMs
16
+ cmux status <id> # Show VM details and URLs
17
+ cmux pause <id> # Pause VM (preserves state, saves cost)
18
+ cmux resume <id> # Resume paused VM
19
+ cmux delete <id> # Delete VM permanently
20
+
21
+ # Access VM
22
+ cmux code <id> # Open VS Code in browser
23
+ cmux ssh <id> # SSH into VM
24
+ cmux vnc <id> # Open VNC desktop
25
+ cmux pty <id> # Interactive terminal session
26
+
27
+ # Work with VM
28
+ cmux exec <id> "cmd" # Run command in VM
29
+ cmux sync <id> <path> # Sync local files to VM
30
+ cmux sync <id> <path> --pull # Pull files from VM
31
+
32
+ # Browser Automation (control Chrome in VNC)
33
+ cmux computer open <id> <url> # Navigate to URL
34
+ cmux computer snapshot <id> # Get interactive elements (@e1, @e2...)
35
+ cmux computer click <id> <selector> # Click element (@e1 or CSS selector)
36
+ cmux computer type <id> "text" # Type into focused element
37
+ cmux computer fill <id> <sel> "value" # Clear and fill input
38
+ cmux computer screenshot <id> [file] # Take screenshot
39
+ cmux computer press <id> <key> # Press key (enter, tab, escape)
40
+ ```
41
+
42
+ ## VM IDs
43
+
44
+ VM IDs look like `cmux_abc12345`. Always use the full ID when running commands.
45
+
46
+ ## Common Workflows
47
+
48
+ ### Create and access a VM
49
+ ```bash
50
+ cmux start ./my-project # Creates VM, syncs directory, returns ID
51
+ cmux code cmux_abc123 # Opens VS Code
52
+ ```
53
+
54
+ ### Run commands remotely
55
+ ```bash
56
+ cmux exec cmux_abc123 "npm install"
57
+ cmux exec cmux_abc123 "npm run dev"
58
+ ```
59
+
60
+ ### Sync files
61
+ ```bash
62
+ cmux sync cmux_abc123 . # Push current dir to VM
63
+ cmux sync cmux_abc123 ./dist --pull # Pull build output from VM
64
+ ```
65
+
66
+ ### Browser automation
67
+ ```bash
68
+ cmux computer open cmux_abc123 "https://localhost:3000"
69
+ cmux computer snapshot cmux_abc123 # See clickable elements
70
+ cmux computer click cmux_abc123 @e1 # Click first element
71
+ ```
72
+
73
+ ### End of session
74
+ ```bash
75
+ cmux pause cmux_abc123 # Pause to save costs (can resume later)
76
+ # OR
77
+ cmux delete cmux_abc123 # Delete permanently
78
+ ```
79
+
80
+ ## Tips
81
+
82
+ - Run `cmux login` first if not authenticated
83
+ - Use `cmux whoami` to check current user and team
84
+ - Use `cmux ls` to see all VMs and their states
85
+ - Paused VMs preserve state and can be resumed instantly
86
+ - The `cmux pty` command requires an interactive terminal
87
+ - Browser automation commands work on the Chrome instance in the VNC desktop
package/README.md CHANGED
@@ -1,11 +1,6 @@
1
1
  # cmux
2
2
 
3
- A single-executable web app multiplexer with built-in Convex backend. cmux allows you to run multiple coding agent CLIs in parallel across different tasks, each with their own isolated environment.
4
-
5
- ## Features
6
-
7
- - 🌐 Web-based UI for managing tasks
8
- - 🐳 Docker integration for isolated environments
3
+ Cloud VMs for development - spawn isolated dev environments instantly.
9
4
 
10
5
  ## Installation
11
6
 
@@ -13,40 +8,65 @@ A single-executable web app multiplexer with built-in Convex backend. cmux allow
13
8
  npm install -g cmux
14
9
  ```
15
10
 
16
- Or download the binary directly from the releases page.
17
-
18
- ## Usage
19
-
20
- Simply run:
11
+ ## Quick Start
21
12
 
22
13
  ```bash
23
- cmux
24
- ```
14
+ # Login
15
+ cmux login
25
16
 
26
- This will:
17
+ # Create a VM
18
+ cmux start # Returns ID like cmux_abc123
27
19
 
28
- 1. Start a local Convex backend on port 9777
29
- 2. Start the web server on port 9776
30
- 3. Open your browser to http://localhost:9776
20
+ # Access the VM
21
+ cmux code cmux_abc123 # Open VS Code in browser
22
+ cmux ssh cmux_abc123 # SSH into VM
31
23
 
32
- ### Options
24
+ # Run commands
25
+ cmux exec cmux_abc123 "npm install"
33
26
 
34
- ```bash
35
- cmux --port 8080 # Use a different port
36
- cmux --help # Show all options
27
+ # Manage lifecycle
28
+ cmux pause cmux_abc123 # Pause (preserves state)
29
+ cmux resume cmux_abc123 # Resume
30
+ cmux delete cmux_abc123 # Delete permanently
31
+
32
+ # List all VMs
33
+ cmux ls
37
34
  ```
38
35
 
39
- ## First Run
36
+ ## Commands
37
+
38
+ | Command | Description |
39
+ |---------|-------------|
40
+ | `cmux login` | Login via browser |
41
+ | `cmux start [path]` | Create new VM, optionally sync directory |
42
+ | `cmux ls` | List all VMs |
43
+ | `cmux code <id>` | Open VS Code in browser |
44
+ | `cmux vnc <id>` | Open VNC desktop in browser |
45
+ | `cmux ssh <id>` | SSH into VM |
46
+ | `cmux pty <id>` | Open interactive terminal |
47
+ | `cmux exec <id> "cmd"` | Execute command |
48
+ | `cmux sync <id> <path>` | Sync files to VM |
49
+ | `cmux pause <id>` | Pause VM |
50
+ | `cmux resume <id>` | Resume VM |
51
+ | `cmux delete <id>` | Delete VM |
52
+
53
+ ## Browser Automation
40
54
 
41
- On first run, cmux will extract its bundled files to `~/.cmux/`. This includes:
55
+ Control Chrome in the VNC desktop:
42
56
 
43
- - The Convex backend binary and database
44
- - Web application static files
45
- - Configuration files
57
+ ```bash
58
+ cmux computer open cmux_abc123 https://example.com
59
+ cmux computer snapshot cmux_abc123 # Get interactive elements
60
+ cmux computer click cmux_abc123 @e1 # Click element
61
+ cmux computer type cmux_abc123 "hello" # Type text
62
+ cmux computer screenshot cmux_abc123 # Take screenshot
63
+ ```
46
64
 
47
- ## Development
65
+ ## Platform Support
48
66
 
49
- cmux is part of the cmux project. See the main repository for development instructions.
67
+ - macOS (Apple Silicon & Intel)
68
+ - Linux (x64 & ARM64)
69
+ - Windows (x64)
50
70
 
51
71
  ## License
52
72
 
package/bin/cmux ADDED
@@ -0,0 +1,97 @@
1
+ #!/usr/bin/env node
2
+
3
+ const { spawn } = require("child_process");
4
+ const path = require("path");
5
+ const fs = require("fs");
6
+
7
+ const PLATFORMS = {
8
+ "darwin-arm64": "cmux-darwin-arm64",
9
+ "darwin-x64": "cmux-darwin-x64",
10
+ "linux-arm64": "cmux-linux-arm64",
11
+ "linux-x64": "cmux-linux-x64",
12
+ "win32-x64": "cmux-win32-x64",
13
+ };
14
+
15
+ // Map platform to local directory name (for development)
16
+ const LOCAL_DIRS = {
17
+ "darwin-arm64": "darwin-arm64",
18
+ "darwin-x64": "darwin-x64",
19
+ "linux-arm64": "linux-arm64",
20
+ "linux-x64": "linux-x64",
21
+ "win32-x64": "win32-x64",
22
+ };
23
+
24
+ function getBinaryPath() {
25
+ const platform = `${process.platform}-${process.arch}`;
26
+ const pkg = PLATFORMS[platform];
27
+ const localDir = LOCAL_DIRS[platform];
28
+
29
+ if (!pkg) {
30
+ console.error(`cmux: Unsupported platform: ${platform}`);
31
+ console.error(`Supported platforms: ${Object.keys(PLATFORMS).join(", ")}`);
32
+ process.exit(1);
33
+ }
34
+
35
+ const binName = process.platform === "win32" ? "cmux.exe" : "cmux";
36
+
37
+ // Try to find the platform-specific package from node_modules
38
+ try {
39
+ const pkgPath = require.resolve(`${pkg}/package.json`);
40
+ const pkgDir = path.dirname(pkgPath);
41
+ const binPath = path.join(pkgDir, "bin", binName);
42
+
43
+ if (fs.existsSync(binPath)) {
44
+ return binPath;
45
+ }
46
+ } catch (e) {
47
+ // Package not found in node_modules
48
+ }
49
+
50
+ // Try local development path (sibling directory)
51
+ const localBinPath = path.join(__dirname, "..", "..", localDir, "bin", binName);
52
+ if (fs.existsSync(localBinPath)) {
53
+ return localBinPath;
54
+ }
55
+
56
+ console.error(`cmux: Could not find binary for platform: ${platform}`);
57
+ console.error(`Make sure ${pkg} is installed.`);
58
+ console.error("");
59
+ console.error("Try reinstalling with:");
60
+ console.error(" npm install cmux");
61
+ process.exit(1);
62
+ }
63
+
64
+ function main() {
65
+ const binPath = getBinaryPath();
66
+ const args = process.argv.slice(2);
67
+
68
+ // Use spawn for better signal handling (especially for PTY)
69
+ const child = spawn(binPath, args, {
70
+ stdio: "inherit",
71
+ windowsHide: true,
72
+ });
73
+
74
+ child.on("error", (err) => {
75
+ console.error(`cmux: Failed to start: ${err.message}`);
76
+ process.exit(1);
77
+ });
78
+
79
+ child.on("exit", (code, signal) => {
80
+ if (signal) {
81
+ // Re-raise the signal
82
+ process.kill(process.pid, signal);
83
+ } else {
84
+ process.exit(code ?? 0);
85
+ }
86
+ });
87
+
88
+ // Forward signals to child
89
+ const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
90
+ for (const sig of signals) {
91
+ process.on(sig, () => {
92
+ child.kill(sig);
93
+ });
94
+ }
95
+ }
96
+
97
+ main();
package/lib/postinstall.js ADDED
@@ -0,0 +1,29 @@
1
+ #!/usr/bin/env node
2
+
3
+ // Post-install message for cmux
4
+ // Only show in interactive terminals to avoid noise in CI
5
+
6
+ const isCI = process.env.CI === 'true' ||
7
+ process.env.CONTINUOUS_INTEGRATION === 'true' ||
8
+ process.env.BUILD_NUMBER !== undefined ||
9
+ process.env.GITHUB_ACTIONS === 'true';
10
+
11
+ const isInteractive = process.stdout.isTTY && !isCI;
12
+
13
+ if (isInteractive) {
14
+ const message = `
15
+ ┌─────────────────────────────────────────────────────────┐
16
+ │ │
17
+ │ ✨ cmux installed successfully! │
18
+ │ │
19
+ │ Get started: │
20
+ │ $ cmux login # Login to your account │
21
+ │ $ cmux start # Create a cloud VM │
22
+ │ $ cmux --help # See all commands │
23
+ │ │
24
+ │ Documentation: https://cmux.sh/docs │
25
+ │ │
26
+ └─────────────────────────────────────────────────────────┘
27
+ `;
28
+ console.log(message);
29
+ }
package/llms.txt ADDED
@@ -0,0 +1,70 @@
1
+ # cmux
2
+
3
+ > Cloud VMs for development - spawn isolated dev environments instantly
4
+
5
+ cmux is a CLI tool for managing cloud development VMs. It provides instant access to fully configured development environments with VS Code, VNC desktop, SSH, and browser automation.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ npm install -g cmux
11
+ ```
12
+
13
+ ## Commands
14
+
15
+ ### Authentication
16
+ - `cmux login` - Login via browser
17
+ - `cmux logout` - Logout
18
+ - `cmux whoami` - Show current user and team
19
+
20
+ ### VM Management
21
+ - `cmux start [path]` - Create new VM, optionally sync a directory
22
+ - `cmux ls` - List all VMs (aliases: list, ps)
23
+ - `cmux status <id>` - Show VM status and URLs
24
+ - `cmux pause <id>` - Pause VM (preserves state)
25
+ - `cmux resume <id>` - Resume paused VM
26
+ - `cmux delete <id>` - Delete VM permanently
27
+
28
+ ### Accessing VMs
29
+ - `cmux code <id>` - Open VS Code in browser
30
+ - `cmux ssh <id>` - SSH into VM
31
+ - `cmux vnc <id>` - Open VNC desktop in browser
32
+ - `cmux pty <id>` - Interactive terminal session
33
+
34
+ ### Working with VMs
35
+ - `cmux exec <id> "command"` - Execute command in VM
36
+ - `cmux sync <id> <path>` - Sync local directory to VM
37
+ - `cmux sync <id> <path> --pull` - Pull from VM to local
38
+
39
+ ### Browser Automation
40
+ Control Chrome running in the VNC desktop:
41
+ - `cmux computer open <id> <url>` - Navigate to URL
42
+ - `cmux computer snapshot <id>` - Get accessibility tree with element refs (@e1, @e2)
43
+ - `cmux computer click <id> <selector>` - Click element (use @ref or CSS selector)
44
+ - `cmux computer type <id> "text"` - Type into focused element
45
+ - `cmux computer fill <id> <selector> "value"` - Clear and fill input
46
+ - `cmux computer screenshot <id> [file]` - Take screenshot
47
+ - `cmux computer press <id> <key>` - Press key (enter, tab, escape, etc.)
48
+
49
+ ## Examples
50
+
51
+ Create a VM and run a dev server:
52
+ ```bash
53
+ cmux start ./my-app
54
+ cmux exec cmux_abc123 "npm install && npm run dev"
55
+ cmux code cmux_abc123
56
+ ```
57
+
58
+ Automate browser testing:
59
+ ```bash
60
+ cmux computer open cmux_abc123 "http://localhost:3000"
61
+ cmux computer snapshot cmux_abc123
62
+ cmux computer click cmux_abc123 @e1
63
+ cmux computer screenshot cmux_abc123 test.png
64
+ ```
65
+
66
+ ## Links
67
+
68
+ - Homepage: https://cmux.sh
69
+ - Documentation: https://cmux.sh/docs
70
+ - GitHub: https://github.com/manaflow-ai/cmux
package/package.json CHANGED
@@ -1,39 +1,45 @@
1
1
  {
2
2
  "name": "cmux",
3
- "version": "0.2.39",
4
- "description": "Open source Claude Code manager that supports Codex/Gemini/OpenCode/Amp CLI",
3
+ "version": "0.3.1",
4
+ "description": "Cloud VMs for development - spawn isolated dev environments instantly",
5
+ "keywords": [
6
+ "cli",
7
+ "devbox",
8
+ "cloud",
9
+ "vm",
10
+ "development",
11
+ "sandbox",
12
+ "remote",
13
+ "vscode"
14
+ ],
15
+ "homepage": "https://cmux.sh",
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/manaflow-ai/cmux.git",
19
+ "directory": "packages/cmux-devbox"
20
+ },
21
+ "license": "MIT",
22
+ "author": "Manaflow",
5
23
  "bin": {
6
- "cmux": "cmux-cli"
24
+ "cmux": "bin/cmux"
7
25
  },
8
26
  "files": [
9
- "cmux-cli",
10
- "README.md"
27
+ "bin",
28
+ "lib",
29
+ "AGENTS.md",
30
+ "llms.txt"
11
31
  ],
12
- "keywords": [
13
- "Claude Code",
14
- "Codex",
15
- "Gemini",
16
- "OpenCode",
17
- "Claude Opus",
18
- "Claude Sonnet",
19
- "Coding CLI",
20
- "multiplexer",
21
- "Grok",
22
- "Amp",
23
- "Qwen",
24
- "Rovo",
25
- "tmux"
26
- ],
27
- "author": "Manaflow",
28
- "license": "MIT",
29
- "engines": {
30
- "node": ">=16.0.0"
32
+ "scripts": {
33
+ "postinstall": "node lib/postinstall.js"
31
34
  },
32
- "publishConfig": {
33
- "access": "public"
35
+ "optionalDependencies": {
36
+ "cmux-darwin-arm64": "0.1.0",
37
+ "cmux-darwin-x64": "0.1.0",
38
+ "cmux-linux-arm64": "0.1.0",
39
+ "cmux-linux-x64": "0.1.0",
40
+ "cmux-win32-x64": "0.1.0"
34
41
  },
35
- "repository": {
36
- "type": "git",
37
- "url": "git+https://github.com/manaflow-ai/cmux.git"
42
+ "engines": {
43
+ "node": ">=16"
38
44
  }
39
45
  }
package/cmux-cli DELETED
Binary file