Mirafold

Mirafold is a browser interface for the coding agents you already use—Claude Agent, Codex, OpenCode, or Gemini CLI—with generative UI layered on top. The agent still runs on your machine with its own engine, credentials, configuration, and permission model.

Mirafold is in public beta. Bug reports and rough edges are welcome in the issue tracker.

• Faithful integrations with Claude Agent, Codex, OpenCode, and Gemini CLI—one adapter per agent, with no generic replacement agent in the middle.
• Streamed markdown plus 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 mission-control page, and a compact in-session cockpit for supervising and moving among several sessions without leaving the current one.
• Read-only workspace browsing and Git change review beside the conversation.
• A real pseudo-terminal (PTY) for ! commands, including interactive programs and password prompts, inside 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 ⧉ pair button in the status bar is where this lives: with an active Mirafold Pro license key it shows the pairing QR; without one — or with a key the billing backend refuses — it says so and links to mirafold.com/pay.

Mirafold drives a real coding agent with access to your filesystem and shell. Review permission prompts, use it only in directories you are prepared to give an agent access to, and read the security policy before exposing or pairing a session.

Mirafold requires Node.js 22 or newer.

Install it globally, move into the project you want the agent to work in, and start the daemon:

npm install --global mirafold
mirafold

The command binds a local server to loopback, opens the browser, and uses the current directory as the default workspace. Useful launcher options:

mirafold --help
mirafold --no-open
mirafold --verbose

Use npx mirafold only inside a project you already trust: npm exposes project-local executables to commands launched through npx. The global install avoids that package-shadowing path; it does not make an unfamiliar checkout safe.

AgentPicker asks for 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 usable live backend is available, the session runs the built-in scripted demo so the entire interface can be explored without model traffic.

Optional Mirafold settings are documented in .env.example and summarized by mirafold --help. Local and hosted open-model setups are covered in docs/local-models.md.

Inside a session:

• Type ordinary prompts in the prompt box.
• Prefix a command with ! to run it in Mirafold's interactive shell; the agent then sees the transcript as its own turn, as in the terminal. Prefix it with !! to run it the same way but shell-only — the agent never sees it.
• Open / for mission control and /s/<session-id> for a session viewport.
• Open Cockpit from the activity bar (the left edge) to preview, prompt, stop, end, or switch directly among live sessions; it follows you across session switches 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 stay visible with their outcomes (exit codes, durations, a preview of the last lines), routine reads and searches group into one line, reasoning collapses to a single "Thinking" control, and a subagent or background task shows its state and its retained report. show details in the status bar opens everything — reasoning, each routine call, inputs, and the retained output — for this browser tab only. Large outputs keep their beginning and end; the transcript says how much fell between them rather than implying it kept it all. If you reattach after the daemon's replay buffer has dropped older history, the transcript says that too instead of pretending the session started where the buffer does.

The repository is one TypeScript package. It uses Yarn 1.22.22 and requires Node.js 22 or newer.

git clone https://github.com/mirafold/mirafold.git
cd mirafold
corepack enable
yarn install
yarn dev

Open http://localhost:5173. The Vite development server proxies the local daemon, and a credential-free agent choice uses the scripted demo backend. yarn dev starts the daemon on port 3100 (PORT in the dev script) and the proxy reads the same PORT variable; set PORT before running either half on its own so they agree.

Build and exercise the packaged path with:

yarn build
node bin/mirafold.js

The main verification commands are:

See CONTRIBUTING.md for contribution rules and the required test tier for a change.

The local daemon adapts each agent's native event stream into the shared protocol in server/protocol.ts. A session registry owns the warm agent sessions, replay history, and browser attachments. The React client keeps shell-owned controls separate from the agent-controlled output zone, where validated registry components and sandboxed artifacts render.

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.

Mirafold's own code is licensed under the MIT License. Integrated agent engines and third-party packages retain their own 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 or endorsed by Anthropic, OpenAI, the OpenCode project, or Google.