Mimi Remote

Continue your computer's agent sessions on iPhone or iPad.

An open-source, native mobile workspace for Codex and Claude Code.
Connect directly to your computer and pick up sessions across devices without rebuilding context—follow work live, continue conversations, and handle approvals.

中文文档  ·  iOS build guide  ·  Project status (Chinese)

_{Continue computer sessions on mobile, control multiple devices, and pick up Codex or Claude Code without starting over.}

Mimi Remote connects directly to your macOS, Windows, or Linux computer through Tailscale or the same local network. The project does not operate a relay, account system, or hosted session service. Your computer remains the control plane; data you intentionally send to Codex, Claude Code, GitHub, voice transcription, or MCP is still handled by those services under their own terms.

Mimi Remote is an independent third-party project. It is not affiliated with, endorsed by, or a product of OpenAI, Anthropic, or Tailscale. Codex is the primary supported runtime; the optional Claude Code bridge is experimental.

Install the public release from the App Store where available. TestFlight remains available for beta builds, and developers can build from source.

   

_{iPhone · same capabilities in one column: continue sessions, follow progress, handle approvals, control tasks.
iPad · the same sessions and controls opened into a multi-column workspace with more context.}

Both devices share the complete session, approval, and task-control surface; only the layout, information density, and input ergonomics change. The native SwiftUI interface tunes compact navigation, wide-screen columns, touch feedback, and transitions for each device. With Reduce Motion enabled, movement falls back to restrained fades or static feedback. These images reuse the current web/assets capture set and come from Debug-only seeded UI with demo hosts, projects, sessions, paths, and usage values—never a maintainer's live workspace or credentials. The interface uses the Simplified Chinese localization; the app also supports English.

Carry the session from your computer to mobile

The common need is rarely “open a terminal on a phone.” It is to leave your computer and keep the same agent session moving without explaining the context again.

• Continue: pick up existing sessions across your computer, iPhone, and iPad instead of starting over when you leave the desk.
• Follow live: see whether a task is thinking, waiting, failed, or complete while structured replies and execution progress arrive.
• Stay in control: add context, queue the next instruction, change model or reasoning, answer a prompt, approve an action, or interrupt the turn.

When you need to finish deeper development work, advanced tools can inspect diffs, manage Worktrees, stage a file or hunk, commit, push, and open a draft pull request. None of those tools is required to use Mimi Remote.

More than a pocket terminal

• Mimi Remote groups Codex and Claude Code messages, reasoning, commands, tool calls, approvals, and work into a readable timeline.
• New Codex sessions receive a concise model-generated title from the host computer; title generation is asynchronous and never blocks the conversation.
• Model, reasoning level, Skill, speed, permission mode, and queued turns stay next to the composer.
• Markdown, images, file references, voice input, and safe Quick Look reads work as mobile-native content.
• Spacing, hierarchy, touch feedback, and transitions are tuned separately for iPhone and iPad; Reduce Motion keeps the same state changes clear without spatial effects.
• Multiple host profiles keep separate tokens in Keychain; one active connection keeps the mental model simple.
• Readiness checks, reconnection, diagnostics, and bounded log export help recover without returning to the desk.

Designed around context, not screen size

Mimi Remote keeps the same project and session model across devices, but each surface follows the way that device is actually used. iPhone keeps one-handed navigation compact, iPad opens the same capabilities into a context-preserving multi-column workbench, and the host computer continues running the agents. The device changes the presentation, not the available capabilities.

   

_{Appearance is first-class · light or dark mode, workspace icon sets, and editor-inspired themes.
Usage and host state stay visible · token windows, connected hosts, language, model, and permissions share one home.}

_{The 340-point Mac menu keeps host health, Codex and Claude runtime state, quota rings, pairing, diagnostics, and recovery actions one click away.}

The hierarchy is intentional:

• Preserve context: iPhone keeps the current task close in a compact hierarchy; the iPad sidebar keeps projects and sessions visible while the detail area changes. Layout changes without removing session capability.
• Disclose complexity progressively: common status and actions stay close to the task, while setup, pairing, diagnostics, and deeper preferences move into focused surfaces.
• Show state before action: connection health, runtime readiness, remaining quota, and permission mode are visible before controls that can change or interrupt work.
• Use each platform natively: compact touch hierarchy on iPhone, multi-column workbench on iPad, and a dense menu bar utility on Mac — not one layout stretched across three screens.

The mobile images above are the same current assets used by the Mimi Remote website and come exclusively from Debug-only seeded UI. The Mac menu image uses the same source tree and the public mimi-demo.local hostname; capturing it did not restart or replace the installed Mac service. None of these public screenshots contains a real token, private address, personal path, or live project content.

Architecture

flowchart LR
    Mobile["iPhone / iPad<br/>Mimi Remote"]
    Gateway["Your computer<br/>agentd secure gateway"]
    Codex["Codex<br/>App Server"]
    Desktop["Codex Desktop<br/>local or SSH"]
    Claude["Claude Code<br/>experimental bridge"]

    Mobile <-->|"LAN or Tailscale<br/>live sessions and approvals"| Gateway
    Gateway <--> Codex
    Desktop <-->|"SSH app-server proxy"| Codex
    Gateway <--> Claude

This repository ships the complete link: the native iPhone/iPad app, the Go agentd gateway for macOS, Windows, and Linux, the Mac menu bar app, the Windows and Linux tray apps, and the Claude Code compatibility bridge. The mobile app connects only to your own host computer, so project files, session history, and runtime credentials stay on that computer.

• Direct and responsive: private-network REST and WebSocket connections carry live output, follow-up messages, task controls, and approvals without a Mimi-operated application relay.
• Platform-specific Codex transport: Linux and local terminal clients share one resident App Server through Codex's standard Unix control socket. macOS reaches the same socket through SSH, while Windows lets agentd own a loopback-only WebSocket App Server. None of these paths uses Desktop private IPC.
• Two runtimes, one mobile experience: Codex is the primary runtime, while the optional Claude Code bridge adapts its sessions and approvals to the same structured interface.
• A small, explicit trust boundary: agentd handles authentication, workspace authorization, and runtime routing on the host computer. That computer must remain awake and privately reachable.

For protocol details and exact capability boundaries, see project status and the Claude bridge architecture.

Prerequisites

Check these before you install:

• Required: an iPhone or iPad running iOS/iPadOS 18 or later, a macOS, Windows, or Linux computer that can keep the host service running, and Codex CLI 0.149.1 or later installed and ready on that computer. Complete the runtime's own authentication on the host; Mimi Remote connects only to the agentd gateway and does not receive or manage runtime credentials or billing. See the official Codex authentication guide. iOS 26+ keeps the full Liquid Glass and on-device Apple Speech experience; iOS 18–25 uses simpler system materials and Codex voice transcription.
• Network: devices on the same trusted LAN can connect directly; Tailscale is not required. Across networks, use the same Tailnet or a secure HTTPS endpoint you administer. Never expose agentd's plain HTTP endpoint directly to the public Internet.
• Optional runtime: Claude Code is experimental, disabled by default, and cannot replace Codex. If you enable it, install and authenticate Claude Code separately using an option in the official Claude Code setup guide; Codex CLI remains required.
• iOS installation today: install the public release from the App Store where available. Use TestFlight for beta builds, or build from source with a Mac, Xcode 26 or later with the iOS 26 SDK, and XcodeGen; see the iOS build guide.
• Developer-only tools: the normal packaged host install does not require Go or Rust. Those tools are only needed for backend or bridge source development. See the full install, upgrade, and rollback guide for platform details and current package availability.

Install and run

First installation in four steps

1. Prepare Codex: install Codex CLI, complete its own authentication on the host, and confirm the runtime is ready. Mimi Remote does not configure provider credentials or billing.
2. Install and start the host: follow the platform installation guide, finish first-run setup, and confirm the service is ready.
3. Install the iOS app: download Mimi Remote from the App Store where available, or join the Mimi Remote TestFlight for beta builds. Developers can instead follow the iOS build guide to run it from source.
4. Pair: open the host's pairing action (or run agentd pair --qr-only) and scan the short-lived QR code in Mimi Remote.

Windows host

Windows 10/11 x64 is supported as an agentd host. Install and sign in to Codex CLI 0.149.1 or later as the same Windows user, then download the versioned Mimi-Remote-Setup-*.exe, .sha256, and .metadata.json files from GitHub Releases. Verify the SHA-256 before running the installer. An unsigned-release package is expected to report NotSigned and can trigger Microsoft Defender SmartScreen.

The per-user installer registers a limited Task Scheduler task and preserves configuration under %APPDATA%\mimi-remote during upgrades. agentd owns one Codex App Server at ws://127.0.0.1:4222, waits for a real protocol initialization, and stops the complete child process tree with the service. This loopback transport stays on the Windows host and does not use Desktop private IPC.

Private-LAN access is opt-in. Setup only enables it on a Private Windows network profile and limits the firewall rule to LocalSubnet; otherwise the host remains loopback-only unless Tailscale is available. See the full install, upgrade, and rollback guide for verification and recovery commands.

Linux host

The Linux release includes a desktop tray with host status, Tailcat/Tailscale/LAN pairing, diagnostics, logs, and service controls. It uses theme-aware symbolic icons and StatusNotifierItem on compatible desktops; QR codes and confirmations open in your terminal. See Linux desktop tray for desktop requirements and recovery steps.

Linux uses the release archive and a per-user systemd service. Install and sign in to Codex CLI 0.149.1 or later as the same Linux user, verify the release checksums, extract the archive, and run bash ./scripts/install-linux.sh install.

By default, Linux does not require sshd, an SSH key, or changes to authorized_keys. agentd attaches to ~/.codex/app-server-control/app-server-control.sock; if it is absent, setup starts one resident Codex App Server in an independent user-systemd scope. A local terminal client launched with codex --remote unix:// and Mimi can therefore open the same Thread through the same backend, and restarting agentd does not stop that backend. An explicit AGENTD_APP_SERVER_SSH_TARGET remains available for advanced remote-host deployments.

macOS host

Requirements:

• A Mac running macOS 15 or later, with Codex CLI installed and signed in.
• The Mac and iPhone/iPad connected to the same private network. Tailscale is recommended for access across different networks but is optional for same-LAN use.

For the normal setup path, download Mimi-Remote-Mac.dmg and its SHA-256 file, verify the checksum, open the DMG, drag Mimi Remote Mac to Applications, then finish first-run setup from the menu bar. The app includes agentd and the compatible Claude bridge; Homebrew, Go, Rust, and Xcode are not required for the Mac host.

For command-line installation, server use, or recovery:

brew update
brew install gaixianggeng/tap/mimi-remote

codex --version
codex app-server --help
agentd up

Before the first start, enable Remote Login and make sure ssh 127.0.0.1 true succeeds without a password prompt. agentd supplies common Homebrew, npm, and mise paths when it checks Codex through a non-interactive SSH session; agentd doctor reports any remaining runtime-path problem. agentd up creates private local configuration, connects through localhost SSH to the shared Unix App Server, waits for a real protocol initialization, and prints a short-lived pairing QR code. It prefers Tailscale when available; otherwise it enables same-LAN access and publishes the current private LAN address. See Shared SSH App Server for Desktop setup and runtime boundaries.

Useful commands:

agentd status
agentd pair
agentd doctor --fix
agentd logs -n 200
agentd up --no-pair
agentd restart
agentd restart --no-pair
agentd stop

On macOS, agentd restart uses one atomic launchd kickstart, so it is safe to trigger from a remote task hosted by the current service. Do not run brew services restart mimi-remote directly from such a task. From an agent, automation, or retained remote log, use agentd up --no-pair / agentd restart --no-pair so the output contains no pairing QR code, endpoint, or long-lived access token. agentd up --no-pair --json returns only the version, readiness state, and safe warnings rather than the complete setup result. When pairing is needed, have the user run agentd pair --qr-only in a local terminal.

For macOS, Windows, and Linux upgrade/recovery steps, see Install, upgrade, and rollback (Chinese). Maintainers can find the daily Internal TestFlight and formal host release flow in Nightly and release (Chinese).

To let Codex perform the same install, upgrade, diagnosis, and rollback workflow with the repository's safety constraints, install the standalone Skill from:

https://github.com/gaixianggeng/mimi-remote/tree/main/packaging/skill/install-mimi-remote

Ask $skill-installer to install that GitHub path. Each GitHub Release also includes install-mimi-remote.zip and its SHA-256 file for an auditable, versioned copy.

Install the iOS app

The current source tree supports iOS/iPadOS 18 or later; App Store availability and minimum OS requirements follow the current listing for each region. Install the public release from the App Store where available, or join the Mimi Remote TestFlight for beta builds. iOS 26+ gets the full advanced visual and on-device speech experience; earlier supported systems use deliberate fallbacks for unsupported capabilities.

To build the app from source instead, use a Mac with Xcode 26 or later and install XcodeGen before generating the Xcode project:

brew install xcodegen

xcodegen generate \
  --spec ios/MimiRemote/project.yml \
  --project ios/MimiRemote

open ios/MimiRemote/MimiRemote.xcodeproj

In Xcode, select the MimiRemote scheme, your development team, and an iPhone or iPad target, then Run. Xcode's Run button always follows the destination selected in its own toolbar and is not part of the command-line automatic selector, so verify that target explicitly. On first launch, scan the QR code printed by agentd up or agentd pair. The signed QR ticket can be reused during its 10-minute lifetime and never contains the long-lived token. Manual connection is available as a fallback.

Command-line daily builds and deployments have one entry point: bash ./scripts/ios-dev.sh build|run. It deterministically leases an available, paired USB iOS device first, then a currently reachable local-network device. The fixed iPad Pro 13-inch (M5) Simulator is used only when no reachable physical device is detected; if physical devices are present but busy, the command fails instead of silently switching device classes. Explicit IOS_DEVICE_ID and IOS_DEVICE_NAME selections support either physical-device transport and fail clearly when that device is not reachable. Tests, snapshots, and CI still require the exact M5 Simulator and never fall back to iPad mini. XcodeBuildMCP stores no device or Simulator target in repository defaults; its Simulator workflow is reserved for those fixed-Simulator tasks. Run bash ./scripts/ios-dev.sh target and bash ./scripts/ios-dev.sh leases to inspect the decision and current occupancy:

bash ./scripts/ios-dev.sh build-for-testing

Build the backend from source (optional)

go test ./...
go vet ./...

# Foreground development; does not replace the Homebrew service.
go build -trimpath -o bin/agentd ./cmd/agentd
./bin/agentd setup --scan-root "$HOME/code" --browse-root "$HOME"
./bin/agentd serve

For repeated macOS testing against the installed Homebrew service, use the signed handoff pipeline instead of copying an ad-hoc Go binary into the Cellar:

bash ./scripts/restart-agentd-dev-macos.sh

# When triggered from a remote Mimi task:
bash ./scripts/restart-agentd-dev-macos.sh --no-wait
bash ./scripts/restart-agentd-dev-macos.sh --status

It signs each development build with a stable Apple Development identity, hands the replacement to an independent launchd job, verifies readiness, and rolls back automatically. At the beginning of every service start, agentd asynchronously probes configured project, scan, and browse roots; a browse root covering the current Home also probes Desktop, Documents, and Downloads so macOS Files & Folders prompts appear before the first real task. The probe never recursively reads files and never blocks the remote control plane while waiting for a click.

macOS does not provide one background-requestable permission for the entire user Home: Desktop, Documents, and Downloads are separate protected locations, while unattended access to other apps' data requires Full Disk Access. For that use case, add /opt/homebrew/opt/mimi-remote/bin/agentd once under System Settings → Privacy & Security → Full Disk Access. The first migration from an old ad-hoc build can still require one final approval.

Claude Code bridge (experimental)

The Claude runtime is disabled by default. When enabled, agentd supervises one resident alleycat-claude-bridge and attaches mobile WebSocket sessions to it by a stable session key. Each Claude thread owns a headless stdio JSONL process; reconnects replay missed events or reload authoritative history instead of resubmitting turn/start.

The notarized Mac DMG already includes a compatible bridge next to agentd; do not install a second copy with Cargo for that setup. Install the bridge from source only for Homebrew, Linux, or standalone development:

cargo install --git https://github.com/gaixianggeng/mimi-remote.git \
  --locked --force --bin alleycat-claude-bridge alleycat-claude-bridge

command -v alleycat-claude-bridge

Enable it explicitly in the user configuration:

{
  "claude": {
    "enabled": true,
    "bridge_bin": "",
    "args": [],
    "max_concurrent_bridges": 3,
    "env": { "TERM": "xterm-256color" }
  }
}

An empty bridge_bin selects the bridge bundled with Mimi Remote Mac. Homebrew and Linux installations must instead set the absolute path returned by command -v alleycat-claude-bridge. The configuration file contains long-lived credentials: back it up privately, update only the claude f