Mina AI Router

Mina AI Router turns multiple local Codex and Claude CLI sessions into a visible collaboration mesh.

It runs each AI agent in a tmux session on your computer, registers the session with a local MCP router, and gives you a browser console to route work, inspect status, open terminal previews, and watch request activity.

GitHub: stevennana/mina-ai-router

Why Use It

Use Mina AI Router when you want several CLI agents to work together across local projects:

• ask one Codex or Claude session to delegate work to another
• keep every agent visible in tmux
• route tasks through local MCP tools instead of copy-pasting between terminals
• see live agent status, capabilities, terminal previews, and request history in one browser console
• keep orchestration local-first on your machine

Install From GitHub

git clone https://github.com/stevennana/mina-ai-router.git
cd mina-ai-router
npm install
npm run build
npm link
mair version

Start

mair server start --port 3333
mair server status

Open the Web UI:

http://127.0.0.1:3333/

While this server is running, it owns the live router state for that state file. Compatible mair CLI reads and writes route through the running server, so mair health, mair agents, the Web UI, and the MCP endpoint agree on busy/available status without a restart.

mair server start reports success only after the local Mina health endpoint is ready. If startup fails because the port is occupied, or a stale pid file points at a non-Mina process, Mina reports an actionable diagnostic instead of a healthy-looking server.

If the Web UI was rebuilt while an older backend is still running, the health endpoint advertises version, startedAt, and apiCapabilities so the UI can show a clear server restart banner instead of calling missing routes. Run mair server restart or mair server start --restart to bring the backend and UI bundle back into the same API generation.

By default, Mina stores local runtime files under ~/.mair, so mair server status, mair health, and agent commands point at the same local server no matter which project directory you run them from. Set MINA_RUNTIME_DIR, MINA_ROUTER_STATE, or MINA_SERVER_PID only when you intentionally want an isolated test or custom runtime.

Add Codex or Claude

In the Web UI, click Add AI, choose Codex or Claude, select a project folder, and click Add. Mina performs the normal MCP setup and registration automatically. The visible progress moves through Starting, Connecting, and Finishing setup until the agent is Ready. When a known permission prompt requires a decision, use Allow once.

Manual setup remains available for custom profiles and repair work:

# Codex users
mair setup codex --project /path/to/project
mair doctor --client codex --project /path/to/project

# Claude users
mair setup claude --project /path/to/project
mair doctor --client claude --project /path/to/project

If you use both clients, run both setup commands and then mair doctor --client all --project /path/to/project.

Manual MCP repair commands are still documented in the MCP Client Setup guide for unusual client profiles.

Terminal Alternative

From a project directory:

mair codex

or:

mair claude

The terminal commands are useful when you want direct control of the visible tmux session. For the normal path, use Add AI in the Web UI.

Collaborate Between Agents

From a registered Codex or Claude session, ask it to use Mina AI Router:

Use Mina AI Router to ask api_server:
Which REST endpoint should this frontend call for user lookup?
Summarize the method, endpoint, parameters, and source files.

The source agent calls MCP list_agents, selects a target, sends the task with call_agent, and waits for the routed answer.

Mina passes caller identity into MCP results so an agent can recognize itself. list_agents marks the caller with isSelf, and call_agent rejects accidental self-calls unless allowSelfCall: true is provided for diagnostics.

Temporary Remote Share

Temporary Remote Share is available in 0.3.0. It provides temporary Ask-only WebRTC access to one local agent. It is not public TCP port punching and does not expose local HTTP, MCP, filesystem, terminal, or admin APIs.

Remote Share is optional. Mina's local router, Web UI, Add AI, agent-to-agent Ask, MCP, terminal, and administration features work without Twilio or a signaling deployment. The configuration below is required only when an operator chooses to create a production Remote Share.

Select a Ready agent, click Invite someone, and then Copy link. Send that private ten-minute link through your preferred out-of-band channel. The collaborator opens it in a browser and Mina connects automatically. Once connected, remote questions appear in Activity. Click Stop sharing at any time; the link also closes when it expires or the router stops.

Link sharing requires both REMOTE_SHARE_SIGNALING_URL and REMOTE_SHARE_GUEST_URL. In the current implementation, every production share creation also requires TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN, even when WebRTC later selects a direct peer path. Restrictive networks require the TURN route; less restrictive networks may use a direct route from the same ICE configuration. Twilio account secrets never go into the link; the guest receives temporary ICE credentials only.

When link sharing is unavailable, the UI explains the missing configuration and keeps protocol artifacts under Offline/manual connection as an advanced fallback. Follow Remote Share Setup to deploy signaling and map its public HTTPS URL, then use the User Start Guide and Remote Share troubleshooting.

For deterministic local validation:

npm run smoke:remote-share

ICE, STUN, TURN, and RTCIceServer are standard WebRTC contracts. Twilio Network Traversal Service is Mina's first and currently only production adapter for obtaining that standard configuration and short-lived TURN credentials. A future release is intended to support operator-configured or self-hosted standard STUN/TURN providers without changing the guest Ask protocol. The generated link is one-use capability data: if it is expired or already used, create a new invitation instead of reusing it.

Inspect Reliability

The browser console is built for local live operations, not hidden background orchestration. During a two-agent collaboration you can:

• open the routed request detail to inspect lifecycle, parsed answer, raw terminal evidence, and parser diagnostics
• retry, cancel, archive, unarchive, interrupt, or mark recovered requests from the activity panel
• distinguish fresh, stale, missing, generated, manually edited, strong, thin, and missing capability profiles
• inspect MCP preflight state and permission/trust blockers before a new CLI session is routed work
• recover long transactions where the router timed out but the target terminal may still be running
• see health states shared by the CLI and UI: available, busy, stale, missing, needs-attention, and unknown
• use mair health, mair agents, and mair agent <id> to confirm the same status model from a terminal
• trust mair health to report the MCP URL for the matching running server, including non-default ports
• see active server-routed requests as busy from both the browser and CLI read commands

What You Get

• Local HTTP UI at http://127.0.0.1:3333/
• Local MCP endpoint at http://127.0.0.1:3333/mcp
• mair CLI for server and agent controls
• Browser operations console with live flow, inspector, terminal preview, and activity log
• Temporary WebRTC remote-share controls and a standalone guest/reference client
• Agent capability summaries, structured capability profiles, readiness state, and editable metadata
• MCP tools: list_agents, register_agent, call_agent, get_request_status
• Repo-local skill for agent self-registration

Guides

• Roadmap
• Getting Started
• User Start Guide
• Remote Share Setup
• MCP Client Setup
• Skill Install Guide
• HTTP UI and MCP Server
• Troubleshooting
• Release Guide

Development

git clone https://github.com/stevennana/mina-ai-router.git
cd mina-ai-router
npm install
npm run verify