mirafold

Mirafold is a browser interface for the coding agents you are already using, including Claude Agent, Codex, OpenCode, and Gemini CLI, and layers a generative UI on top of them. The agents still run on your own machine, using their own engines, credentials, configuration, and permission models. The project is currently in public beta, and bug reports and feedback are welcome in the issue tracker.

Purpose

Mirafold aims to make the work of terminal coding agents more readable and easier to supervise. It does not replace the agents; instead, it provides an adapter for each supported agent that faithfully presents its output, and on top of that adds real-time visualization and multi-session management capabilities.

Main capabilities

• Faithful integration for Claude Agent, Codex, OpenCode, and Gemini CLI, with one adapter per agent and no generic replacement agent in between.
• Streaming Markdown, as well as live tables, charts, diffs, task lists, diagrams, images, and other interactive components generated through Model Context Protocol (MCP) tools.
• Persistent sessions, multiple attached browser views, a task control page, and a compact in-session cockpit for supervising and switching between multiple sessions without leaving the current session.
• Read-only workspace browsing and Git change review alongside the conversation.
• A real pseudo-terminal (PTY) for ! commands, including interactive programs and password prompts, within a shell-owned UI.
• Optional remote browser and phone access through an end-to-end encrypted relay; provider credentials remain on the machine running Mirafold. The ⧉ pairing button in the status bar is used for this feature: it shows a pairing QR code when you have a valid Mirafold Pro license key; without a key, or when the billing backend rejects the key, it explains the situation and links to mirafold.com/pay.

Usage

Mirafold requires Node.js 22 or later. After installing it globally, go to the project directory where you want the agent to work and start the daemon. The command binds the local server to the loopback address, opens the browser, and uses the current directory as the default workspace.

Only use npx mirafold inside projects you already trust: npm exposes project-local executables through commands started with npx. A global install avoids that package shadowing the path; however, this does not make an unfamiliar checkoutBecome safe.

AgentPicker will ask you to choose a supported agent, one of its detected backends, and a working directory. Mirafold uses the selected agent's native engine and any supported authentication it detects. If no live backend is available, the session runs a built-in scripted demo so you can explore the entire interface without model traffic.

Optional Mirafold settings are documented in .env.example and summarized by mirafold --help. For local and hosted open-model setup, see docs/local-models.md.

Within a session:

• Enter a normal prompt in the prompt box.
• Commands prefixed with ! run in Mirafold's interactive shell; the agent then treats the record as one of its own turns, as if in a terminal. Prefixing with !! runs the same way, but shell-only—the agent never sees it.
• Open / to enter mission control, open /s/<session-id> to enter the session viewport.
• Open Cockpit from the activity bar (left edge) to preview, prompt, stop, end, or switch directly between active sessions; it follows you as you switch between sessions until you close it.
• Use the Files and Changes workspaces to inspect the current directory and its Git working tree changes.

The transcript is compact by default: the agent's messages and every command, edit, and failure remain visible, along with their results (exit code, duration, preview of the last few lines), routine reads and searches are merged into a single line, reasoning is collapsed into a single "Thinking" control, and subagents or background tasks show their status and retained reports. "show details" in the status bar opens everything—reasoning, every routine call, input, and retained output—for the current browser tab only. Large output retains its beginning and end; the transcript states how much was omitted in the middle rather than implying it retained everything. If you reattach after the daemon's replay buffer has discarded older history, the transcript also states this rather than pretending the session starts at the beginning of the buffer.

Development and Architecture

This repository is a TypeScript package using Yarn 1.22.22 and requires Node.js 22 or later. The development server runs on http://localhost:5173。Vite The development server proxies the local daemon, and credential-free agent selection uses the scripted demo backend. yarn dev starts the daemon on port 3100 (PORT in the development script), and the proxy reads the same PORT variable; set PORT before running either half separately so they agree.

The local daemon adapts each agent's native event stream to the shared protocol in server/protocol.ts. The session registry owns hot agent sessions, replay history, and browser attachments. The React client separates shell-owned controls from agent-controlled output areas, the latter rendering validated registry components and sandboxed artifacts.

Read docs/ARCHITECTURE.md for the system model, core contracts, trust boundaries, key flows, and repository map. Adapter authors should also read the normative adapter specification.

Applicable Scenarios and Limitations

Mirafold drives a real coding agent that has access to your filesystem and shell. Review permission prompts, use it only in directories where you are prepared to grant the agent access, and read the security policy before exposing or pairing sessions.

Mirafold's own code is licensed under MIT. Integrated agent engines and third-party packages retain their respective licenses; bundled web dependencies are listed in THIRD-PARTY-NOTICES.md. All product names and trademarks belong to their respective owners. Mirafold is not affiliated with, nor endorsed by, Anthropic, OpenAI, the OpenCode project, or Google.