Mirafold 是一个浏览器界面，用于你已经在使用的编码智能体，包括 Claude Agent、Codex、OpenCode 和 Gemini CLI，并在其上叠加生成式 UI。智能体仍然在你自己的机器上运行，使用其自身的引擎、凭据、配置和权限模型。项目目前处于公开测试阶段，欢迎在问题跟踪器中提交错误报告和反馈。
用途
Mirafold 的目标是让终端编码智能体的工作过程更易读、更易监督。它不替换智能体，而是为每个受支持的智能体提供一个适配器，忠实呈现其输出，并在此基础上增加实时可视化与多会话管理能力。
主要能力
- 对 Claude Agent、Codex、OpenCode 和 Gemini CLI 提供忠实集成，每个智能体一个适配器，中间没有通用替代智能体。
- 流式 Markdown，以及通过 Model Context Protocol（MCP）工具生成的实时表格、图表、差异、任务列表、图表、图片和其他交互组件。
- 持久会话、多个附加的浏览器视图、任务控制页，以及紧凑的会话内驾驶舱，用于在不离开当前会话的情况下监督和切换多个会话。
- 在对话旁边提供只读工作区浏览和 Git 变更审查。
- 为 ! 命令提供真实伪终端（PTY），包括交互式程序和密码提示，位于 shell 拥有的 UI 内。
- 可选通过端到端加密中继实现远程浏览器和手机访问；提供商凭据保留在运行 Mirafold 的机器上。状态栏中的 ⧉ 配对按钮用于此功能：拥有有效的 Mirafold Pro 许可证密钥时显示配对二维码；没有密钥，或计费后端拒绝密钥时，会说明情况并链接到 mirafold.com/pay。
使用方式
Mirafold 需要 Node.js 22 或更高版本。全局安装后，进入希望智能体工作的项目目录并启动守护进程。该命令将本地服务器绑定到回环地址，打开浏览器，并使用当前目录作为默认工作区。
仅在已经信任的项目内使用 npx mirafold：npm 会通过 npx 启动的命令暴露项目本地可执行文件。全局安装可避免该包遮蔽路径；但这不会让不熟悉的检出变得安全。
AgentPicker 会要求选择一个受支持的智能体、其检测到的后端之一以及一个工作目录。Mirafold 使用所选智能体的原生引擎及其检测到的任何受支持认证。如果没有可用的实时后端，会话将运行内置的脚本化演示，以便在没有模型流量的情况下探索整个界面。
可选的 Mirafold 设置记录在 .env.example 中，并由 mirafold --help 汇总。本地和托管的开放模型设置见 docs/local-models.md。
在会话内：
- 在提示框中输入普通提示。
- 以 ! 为前缀的命令会在 Mirafold 的交互式 shell 中运行；智能体随后将记录视为自己的一轮，如同在终端中。以 !! 为前缀则以相同方式运行，但仅限 shell——智能体永远不会看到它。
- 打开 / 进入任务控制，打开 /s/<session-id> 进入会话视口。
- 从活动栏（左边缘）打开 Cockpit，以预览、提示、停止、结束或直接在活动会话之间切换；它会跟随你跨会话切换，直到你关闭它。
- 使用 Files 和 Changes 工作区检查当前目录及其 Git 工作树变更。
转录默认紧凑：智能体的消息以及每条命令、编辑和失败都保持可见，并显示其结果（退出码、持续时间、最后几行的预览），常规读取和搜索合并为一行，推理折叠为单个“Thinking”控件，子智能体或后台任务显示其状态和保留的报告。状态栏中的“show details”会打开所有内容——推理、每次常规调用、输入和保留的输出——仅针对当前浏览器标签页。大输出保留其开头和结尾；转录会说明中间省略了多少，而不是暗示它保留了全部。如果在守护进程的重放缓冲区丢弃较旧历史后重新附加，转录也会说明这一点，而不是假装会话从缓冲区开始处开始。
开发与架构
该仓库是一个 TypeScript 包，使用 Yarn 1.22.22，需要 Node.js 22 或更高版本。开发服务器运行在 http://localhost:5173。Vite 开发服务器代理本地守护进程，无凭据的智能体选择使用脚本化演示后端。yarn dev 在端口 3100 上启动守护进程（开发脚本中的 PORT），代理读取相同的 PORT 变量；在单独运行任一半之前设置 PORT，使它们一致。
本地守护进程将每个智能体的原生事件流适配为 server/protocol.ts 中的共享协议。会话注册表拥有热智能体会话、重放历史和浏览器附件。React 客户端将 shell 拥有的控件与智能体控制的输出区域分开，后者渲染经过验证的注册表组件和沙盒化产物。
阅读 docs/ARCHITECTURE.md 了解系统模型、核心契约、信任边界、关键流程和仓库地图。适配器作者还应阅读规范性适配器规范。
适用场景与限制
Mirafold 驱动一个真实的编码智能体，该智能体可以访问你的文件系统和 shell。请审查权限提示，仅在你准备授予智能体访问权限的目录中使用它，并在暴露或配对会话之前阅读安全政策。
Mirafold 自身代码采用 MIT 许可证。集成的智能体引擎和第三方包保留其各自许可证；捆绑的 Web 依赖列在 THIRD-PARTY-NOTICES.md 中。所有产品名称和商标属于其各自所有者。Mirafold 与 Anthropic、OpenAI、OpenCode 项目或 Google 无关联，也未获其认可。
