modelmux 0.4.0__tar.gz

modelmux-0.4.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Runtime
+/tmp/
+*.log
+
+# uv lock file (tool project, not pinning deps)
+uv.lock

modelmux-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pure-maple
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modelmux-0.4.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: modelmux
+Version: 0.4.0
+Summary: Model multiplexer — unified MCP server for cross-platform multi-model AI collaboration
+Project-URL: Homepage, https://github.com/pure-maple/modelmux
+Project-URL: Repository, https://github.com/pure-maple/modelmux
+Project-URL: Issues, https://github.com/pure-maple/modelmux/issues
+Project-URL: Documentation, https://github.com/pure-maple/modelmux#readme
+Author: pure-maple
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,cli,codex,collaboration,gemini,mcp,modelmux,multi-model,multiplexer
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.20.0
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# modelmux
+
+Model multiplexer — unified MCP server for cross-platform multi-model AI collaboration.
+
+Route tasks to **Codex CLI**, **Gemini CLI**, and **Claude Code CLI** through a single MCP interface with smart routing and caller auto-detection.
+
+## Install
+
+```bash
+# One-command install for Claude Code
+claude mcp add modelmux -s user -- uvx modelmux
+
+# Codex CLI (~/.codex/config.toml)
+# [mcp_servers.modelmux]
+# command = "uvx"
+# args = ["modelmux"]
+
+# Gemini CLI (~/.gemini/settings.json)
+# {"mcpServers": {"modelmux": {"command": "uvx", "args": ["modelmux"]}}}
+```
+
+## Tools
+
+- **`collab_dispatch`** — Send a task to a model and get structured results
+  - `provider`: `"auto"` / `"codex"` / `"gemini"` / `"claude"`
+  - `task`: The prompt to send
+  - `workdir`, `sandbox`, `session_id`, `timeout`, `model`, `profile`, `reasoning_effort`
+- **`collab_check`** — Check which CLIs are available, show detected caller and config
+
+## Smart Routing
+
+`provider="auto"` routes tasks by keyword analysis and auto-excludes the calling platform:
+
+```
+From Claude Code → routes to Codex or Gemini (never back to Claude)
+From Codex CLI → routes to Claude or Gemini (never back to Codex)
+```
+
+## Audit & Policy
+
+Every dispatch call is logged to `~/.config/modelmux/audit.jsonl` for debugging and cost tracking.
+
+Policy enforcement via `~/.config/modelmux/policy.json`:
+
+```json
+{
+  "blocked_providers": ["gemini"],
+  "blocked_sandboxes": ["full"],
+  "max_timeout": 600,
+  "max_calls_per_hour": 30,
+  "max_calls_per_day": 200
+}
+```
+
+`collab_check()` now shows policy summary and audit stats.
+
+## User Configuration
+
+Create `.modelmux/profiles.toml` or `~/.config/modelmux/profiles.toml`:
+
+```toml
+[routing]
+default_provider = "codex"
+
+[[routing.rules]]
+provider = "gemini"
+[routing.rules.match]
+keywords = ["frontend", "react", "css"]
+
+[profiles.budget]
+[profiles.budget.providers.codex]
+model = "gpt-4.1-mini"
+```
+
+## Links
+
+- [Full Documentation](https://github.com/pure-maple/modelmux)
+- [中文文档](https://github.com/pure-maple/modelmux/blob/main/docs/README_CN.md)
+
+## License
+
+MIT

modelmux-0.4.0/README.md

@@ -0,0 +1,82 @@
+# modelmux
+
+Model multiplexer — unified MCP server for cross-platform multi-model AI collaboration.
+
+Route tasks to **Codex CLI**, **Gemini CLI**, and **Claude Code CLI** through a single MCP interface with smart routing and caller auto-detection.
+
+## Install
+
+```bash
+# One-command install for Claude Code
+claude mcp add modelmux -s user -- uvx modelmux
+
+# Codex CLI (~/.codex/config.toml)
+# [mcp_servers.modelmux]
+# command = "uvx"
+# args = ["modelmux"]
+
+# Gemini CLI (~/.gemini/settings.json)
+# {"mcpServers": {"modelmux": {"command": "uvx", "args": ["modelmux"]}}}
+```
+
+## Tools
+
+- **`collab_dispatch`** — Send a task to a model and get structured results
+  - `provider`: `"auto"` / `"codex"` / `"gemini"` / `"claude"`
+  - `task`: The prompt to send
+  - `workdir`, `sandbox`, `session_id`, `timeout`, `model`, `profile`, `reasoning_effort`
+- **`collab_check`** — Check which CLIs are available, show detected caller and config
+
+## Smart Routing
+
+`provider="auto"` routes tasks by keyword analysis and auto-excludes the calling platform:
+
+```
+From Claude Code → routes to Codex or Gemini (never back to Claude)
+From Codex CLI → routes to Claude or Gemini (never back to Codex)
+```
+
+## Audit & Policy
+
+Every dispatch call is logged to `~/.config/modelmux/audit.jsonl` for debugging and cost tracking.
+
+Policy enforcement via `~/.config/modelmux/policy.json`:
+
+```json
+{
+  "blocked_providers": ["gemini"],
+  "blocked_sandboxes": ["full"],
+  "max_timeout": 600,
+  "max_calls_per_hour": 30,
+  "max_calls_per_day": 200
+}
+```
+
+`collab_check()` now shows policy summary and audit stats.
+
+## User Configuration
+
+Create `.modelmux/profiles.toml` or `~/.config/modelmux/profiles.toml`:
+
+```toml
+[routing]
+default_provider = "codex"
+
+[[routing.rules]]
+provider = "gemini"
+[routing.rules.match]
+keywords = ["frontend", "react", "css"]
+
+[profiles.budget]
+[profiles.budget.providers.codex]
+model = "gpt-4.1-mini"
+```
+
+## Links
+
+- [Full Documentation](https://github.com/pure-maple/modelmux)
+- [中文文档](https://github.com/pure-maple/modelmux/blob/main/docs/README_CN.md)
+
+## License
+
+MIT

modelmux-0.4.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "modelmux"
+version = "0.4.0"
+description = "Model multiplexer — unified MCP server for cross-platform multi-model AI collaboration"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "pure-maple" },
+]
+keywords = [
+    "mcp",
+    "ai",
+    "collaboration",
+    "multi-model",
+    "modelmux",
+    "multiplexer",
+    "codex",
+    "gemini",
+    "claude",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp[cli]>=1.20.0",
+    "pydantic>=2.0",
+]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.9.0",
+    "build>=1.0.0",
+    "twine>=6.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/pure-maple/modelmux"
+Repository = "https://github.com/pure-maple/modelmux"
+Issues = "https://github.com/pure-maple/modelmux/issues"
+Documentation = "https://github.com/pure-maple/modelmux#readme"
+
+[project.scripts]
+modelmux = "modelmux.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/modelmux"]
+
+[tool.ruff]
+target-version = "py310"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]

modelmux-0.4.0/src/modelmux/__init__.py

@@ -0,0 +1,3 @@
+"""modelmux — model multiplexer for cross-platform multi-model AI collaboration."""
+
+__version__ = "0.4.0"

modelmux-0.4.0/src/modelmux/adapters/__init__.py

@@ -0,0 +1,21 @@
+"""Model CLI adapters for modelmux."""
+
+from modelmux.adapters.base import AdapterResult, BaseAdapter
+from modelmux.adapters.claude import ClaudeAdapter
+from modelmux.adapters.codex import CodexAdapter
+from modelmux.adapters.gemini import GeminiAdapter
+
+ADAPTERS: dict[str, type[BaseAdapter]] = {
+    "codex": CodexAdapter,
+    "gemini": GeminiAdapter,
+    "claude": ClaudeAdapter,
+}
+
+__all__ = [
+    "BaseAdapter",
+    "AdapterResult",
+    "CodexAdapter",
+    "GeminiAdapter",
+    "ClaudeAdapter",
+    "ADAPTERS",
+]

modelmux-0.4.0/src/modelmux/adapters/base.py

@@ -0,0 +1,252 @@
+"""Base adapter for CLI model bridges."""
+
+from __future__ import annotations
+
+import json
+import os
+import queue
+import shutil
+import subprocess
+import time
+import uuid
+from dataclasses import dataclass
+from threading import Thread
+from typing import Generator
+
+GRACEFUL_SHUTDOWN_DELAY = 0.3
+QUEUE_READ_TIMEOUT = 0.5
+
+
+@dataclass
+class AdapterResult:
+    """Canonical result schema for all model adapters."""
+
+    run_id: str = ""
+    provider: str = ""
+    status: str = "error"  # success | error | timeout
+    summary: str = ""
+    output: str = ""
+    session_id: str = ""
+    duration_seconds: float = 0.0
+    error: str | None = None
+
+    def to_dict(self) -> dict:
+        d = {
+            "run_id": self.run_id,
+            "provider": self.provider,
+            "status": self.status,
+            "summary": self.summary,
+            "output": self.output,
+            "session_id": self.session_id,
+            "duration_seconds": round(self.duration_seconds, 1),
+        }
+        if self.error:
+            d["error"] = self.error
+        return d
+
+
+def is_turn_completed(line: str) -> bool:
+    """Check if a JSONL line indicates turn completion."""
+    try:
+        data = json.loads(line)
+        return data.get("type") == "turn.completed"
+    except (json.JSONDecodeError, AttributeError, TypeError):
+        return False
+
+
+def stream_subprocess(
+    cmd: list[str],
+    cwd: str | None = None,
+    timeout: int = 300,
+    env_overrides: dict[str, str] | None = None,
+) -> Generator[str, None, int]:
+    """Run a subprocess and yield stdout lines via a threaded queue.
+
+    Returns the exit code via generator return value.
+    Uses the battle-tested pattern from GuDaStudio's codexmcp/geminimcp.
+    """
+    resolved = shutil.which(cmd[0])
+    if not resolved:
+        raise FileNotFoundError(f"Command not found: {cmd[0]}")
+    cmd[0] = resolved
+
+    proc_env = None
+    if env_overrides:
+        proc_env = os.environ.copy()
+        proc_env.update(env_overrides)
+
+    process = subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        cwd=cwd,
+        env=proc_env,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+    output_queue: queue.Queue[str | None] = queue.Queue()
+
+    def read_output() -> None:
+        assert process.stdout is not None
+        for line in iter(process.stdout.readline, ""):
+            stripped = line.strip()
+            if stripped:
+                output_queue.put(stripped)
+                if is_turn_completed(stripped):
+                    time.sleep(GRACEFUL_SHUTDOWN_DELAY)
+                    process.terminate()
+                    break
+        process.stdout.close()
+        output_queue.put(None)
+
+    reader = Thread(target=read_output, daemon=True)
+    reader.start()
+
+    start_time = time.monotonic()
+    while True:
+        elapsed = time.monotonic() - start_time
+        if elapsed > timeout:
+            process.terminate()
+            process.wait(timeout=5)
+            return 124  # timeout exit code
+
+        try:
+            line = output_queue.get(timeout=QUEUE_READ_TIMEOUT)
+        except queue.Empty:
+            if process.poll() is not None:
+                break
+            continue
+
+        if line is None:
+            break
+        yield line
+
+    process.wait(timeout=10)
+    return process.returncode or 0
+
+
+class BaseAdapter:
+    """Base class for model CLI adapters."""
+
+    provider_name: str = "unknown"
+
+    def check_available(self) -> bool:
+        """Check if the CLI binary is available on PATH."""
+        return shutil.which(self._binary_name()) is not None
+
+    def _binary_name(self) -> str:
+        raise NotImplementedError
+
+    def build_command(
+        self,
+        prompt: str,
+        workdir: str,
+        sandbox: str = "read-only",
+        session_id: str = "",
+        extra_args: dict | None = None,
+    ) -> list[str]:
+        raise NotImplementedError
+
+    def parse_output(self, lines: list[str]) -> tuple[str, str, str]:
+        """Parse collected output lines.
+
+        Returns (agent_text, session_id, error_text).
+        """
+        raise NotImplementedError
+
+    async def run(
+        self,
+        prompt: str,
+        workdir: str,
+        sandbox: str = "read-only",
+        session_id: str = "",
+        timeout: int = 300,
+        extra_args: dict | None = None,
+        env_overrides: dict[str, str] | None = None,
+    ) -> AdapterResult:
+        """Execute a task and return the canonical result."""
+        run_id = str(uuid.uuid4())[:8]
+        start = time.monotonic()
+
+        if not self.check_available():
+            return AdapterResult(
+                run_id=run_id,
+                provider=self.provider_name,
+                status="error",
+                error=f"{self._binary_name()} not found on PATH",
+            )
+
+        try:
+            cmd = self.build_command(prompt, workdir, sandbox, session_id, extra_args)
+        except Exception as e:
+            return AdapterResult(
+                run_id=run_id,
+                provider=self.provider_name,
+                status="error",
+                error=f"Failed to build command: {e}",
+            )
+
+        lines: list[str] = []
+        exit_code = 0
+        try:
+            gen = stream_subprocess(
+                cmd,
+                cwd=workdir,
+                timeout=timeout,
+                env_overrides=env_overrides,
+            )
+            for line in gen:
+                lines.append(line)
+            # Get the return value (exit code) from the generator
+            try:
+                next(gen)
+            except StopIteration as e:
+                exit_code = e.value if e.value is not None else 0
+        except FileNotFoundError as e:
+            return AdapterResult(
+                run_id=run_id,
+                provider=self.provider_name,
+                status="error",
+                error=str(e),
+                duration_seconds=time.monotonic() - start,
+            )
+        except Exception as e:
+            return AdapterResult(
+                run_id=run_id,
+                provider=self.provider_name,
+                status="error",
+                error=f"Subprocess error: {e}",
+                duration_seconds=time.monotonic() - start,
+            )
+
+        duration = time.monotonic() - start
+
+        if exit_code == 124:
+            return AdapterResult(
+                run_id=run_id,
+                provider=self.provider_name,
+                status="timeout",
+                output="\n".join(lines[-50:]),
+                duration_seconds=duration,
+                error=f"Timed out after {timeout}s",
+            )
+
+        agent_text, new_session_id, error_text = self.parse_output(lines)
+
+        # Generate summary (first 200 chars of agent text)
+        summary = agent_text[:200].replace("\n", " ") if agent_text else ""
+
+        status = "success" if agent_text and not error_text else "error"
+
+        return AdapterResult(
+            run_id=run_id,
+            provider=self.provider_name,
+            status=status,
+            summary=summary,
+            output=agent_text or error_text or "\n".join(lines),
+            session_id=new_session_id or session_id,
+            duration_seconds=duration,
+            error=error_text if error_text else None,
+        )

modelmux-0.4.0/src/modelmux/adapters/claude.py

@@ -0,0 +1,60 @@
+"""Claude Code CLI adapter.
+
+Wraps `claude -p` (print/non-interactive mode).
+Claude outputs plain text, no structured JSON events.
+"""
+
+from __future__ import annotations
+
+from modelmux.adapters.base import BaseAdapter
+
+
+class ClaudeAdapter(BaseAdapter):
+    provider_name = "claude"
+
+    def _binary_name(self) -> str:
+        return "claude"
+
+    def build_command(
+        self,
+        prompt: str,
+        workdir: str,
+        sandbox: str = "read-only",
+        session_id: str = "",
+        extra_args: dict | None = None,
+    ) -> list[str]:
+        cmd = ["claude", "-p", prompt]
+
+        if extra_args:
+            if extra_args.get("model"):
+                cmd.extend(["--model", extra_args["model"]])
+            if extra_args.get("allowed_tools"):
+                for tool in extra_args["allowed_tools"]:
+                    cmd.extend(["--allowedTools", tool])
+
+        if session_id:
+            cmd.extend(["--resume", session_id])
+
+        return cmd
+
+    def parse_output(self, lines: list[str]) -> tuple[str, str, str]:
+        """Parse Claude plain text output.
+
+        Claude -p returns plain text, no JSON structure.
+        Session ID is extracted from the session resume message if present.
+        """
+        output_lines: list[str] = []
+        session_id = ""
+
+        for line in lines:
+            # Claude may output a session line at the start
+            if line.startswith("Session:") or line.startswith("session:"):
+                parts = line.split(":", 1)
+                if len(parts) == 2:
+                    session_id = parts[1].strip()
+                continue
+
+            output_lines.append(line)
+
+        agent_text = "\n".join(output_lines)
+        return agent_text, session_id, ""