MODMUX

One localhost endpoint for supported agents

Use one local Copilot endpoint across your coding agents.

Modmux lets Claude Code, Cline, and Codex share the same local GitHub Copilot gateway so you stop redoing provider setup for each tool.

Install Modmux See how it works

Open source, localhost-only, and reversible by design.

  • One endpoint for Claude Code, Cline, and Codex
  • Anthropic and OpenAI compatible APIs
  • Built-in Copilot quota visibility

$ modmux start

Starts a local gateway and completes GitHub auth

$ modmux configure claude-code

Points your agent at the shared localhost endpoint

$ modmux status

Shows endpoint, auth, and usage state in one place

Claude Code Cline Codex

Why use Modmux

Stop treating each agent like a separate integration project.

Modmux centralizes the messy part of agent setup: provider wiring, local endpoints, usage visibility, and cleanup when you want to back out.

One shared local endpoint

Point supported agents at one stable localhost gateway instead of teaching every tool a different provider-specific config.

Local and reversible

Modmux binds to 127.0.0.1. Supported config changes can be undone with modmux unconfigure when you want to restore the original setup.

Runtime stays visible

Check status, health, models, and Copilot quota usage without guessing what is running behind the scenes.

How it works

The request path stays short, local, and debuggable.

A supported agent talks to Modmux on localhost. Modmux translates compatible request and response shapes, then forwards them through GitHub Copilot.

Supported agent

Claude Code, Cline, or Codex sends requests to one local endpoint instead of maintaining separate provider wiring.

Modmux

Exposes compatible endpoints, translates traffic, and keeps auth, status, and usage visible from the CLI.

  • /v1/messages
  • /v1/chat/completions
  • /v1/responses
  • /v1/models, /v1/usage, /health

GitHub Copilot

Modmux authenticates with GitHub and forwards requests through the Copilot-backed model path with a local-first trust boundary.

Trust boundary: Modmux is a local gateway, not a hosted relay or agent runtime. It keeps the network surface local and the configuration changes explicit.

Proof

Three commands show the product, not just the promise.

Modmux is easiest to understand from the terminal: start the local gateway, configure an agent, and inspect the live endpoint and usage state.

1. Start the local gateway

modmux start

Completes GitHub auth, starts the localhost service, and enables real Copilot usage visibility by default.

2. Point one agent at it

modmux configure claude-code

Writes reversible local config so Claude Code uses the shared endpoint instead of a separate provider setup.

3. Inspect the live state

modmux status curl http://127.0.0.1:11435/v1/usage

Confirms the active endpoint, auth state, and Copilot quota data from the same local runtime.

Install

Install it, authenticate once, and reuse the endpoint everywhere.

The fastest path is still from source. If you do not want the Deno runtime on your machine, use a direct binary from GitHub Releases.

Recommended

From source

Clone the repository and install globally with the current Deno task. This is the easiest way to stay current while the project is moving quickly.

git clone https://github.com/modmux/modmux.git cd modmux deno task install
  1. Run modmux start and complete GitHub auth.
  2. Run modmux configure claude-code.
  3. Confirm the endpoint and usage state with modmux status.

Product roadmap

From foundation to future — Modmux's development phases.

Foundation (Complete)

Core infrastructure that powers the local gateway

Copilot & Multi-Agent

✓ Complete

GitHub auth, daemon startup, and support for Claude Code, Cline, and Codex.

Protocol Translation

✓ Complete

Anthropic and OpenAI compatible APIs with transparent usage data handling.

Cross-Platform Service

✓ Complete

Windows, macOS, and Linux daemon support with unified lifecycle management.

Usage & Observability

✓ Complete

Real-time GitHub Copilot quota tracking and request metrics visible in CLI.

Current (Complete)

Recently shipped features and improvements

Documentation & UX

✓ Complete

Editorial improvements and clarity pass across README and docs.

Compatibility Fixes

✓ Complete

OpenAI tool passthrough and conventional commit release notes.

Upcoming (Planned)

Next phase of local AI features

Ollama Fallback Routing

High Priority

Keep using your coding agent when Copilot is temporarily down. Modmux will gracefully fall back to a local Ollama model you configure.

  • Detect Copilot failures and retry locally
  • Optional Ollama configuration
  • Visible in modmux status

Heuristic Auto Model Selection

High Priority

Send model: "auto" and let Modmux choose between Haiku, Sonnet, and Opus based on request complexity and size.

  • Request-local heuristic classification
  • Deterministic, fully observable decisions
  • Balances speed and quality automatically

Ollama-Powered Classification

High Priority

Optionally run a small local model to improve Auto tier selection beyond hand-written heuristics.

  • Use Phi-3, Mistral, or similar models
  • Fall back to heuristics if unavailable
  • All-local decision logging for future tuning

Cost-Aware Status Display

Medium Priority

See estimated cost and token usage directly in modmux status so you understand what your recent requests are consuming.

  • Per-model usage breakdown
  • Recent cost estimates
  • Machine-readable JSON export

Features are in active development and subject to change. For detailed specs and status, visit the specs folder.

FAQ

Questions that usually block adoption.

Why not configure each agent directly?

You can, but every tool tends to drift into its own config path, provider format, and recovery workflow. Modmux keeps that setup centralized so switching agents does not mean starting over.

Do I need a GitHub Copilot subscription?

Yes. Modmux routes requests through GitHub Copilot, so you need an active Copilot-backed account.

Does Modmux expose an API on my network?

No. The service binds to 127.0.0.1, so it stays local to your machine.

Can I undo a configuration change?

Yes. Supported agent configuration is reversible by design with modmux unconfigure.

Which agents are supported right now?

The built-in registry currently includes Claude Code, Cline, and Codex.

Does Modmux track my Copilot usage?

Yes. By default, Modmux manages the Copilot CLI sidecar needed for real quota visibility through /v1/usage. Run modmux set copilot off if you want to disable it.

Do I need Deno to use Modmux?

Deno is only required for the recommended source install. Downloading a direct binary from GitHub Releases does not require it.