中文 · English
当前项目完全开源，只用作学习使用，项目还比较初级有很多地方需要持续优化，欢迎大家来 star 一同共建~
基于 Python 和 Flet 构建的 Claude Code 桌面 GUI 客户端。
Misaka 将 Claude Code 的强大能力带入精致的原生桌面体验——多轮流式对话、会话管理、文件树浏览、MCP 服务器集成等功能，全部融入简洁的 Material Design 3 界面。
Misaka（御坂），致敬《某科学的超电磁炮》，寓意像御坂网络一样拥有强大的计算和连接能力。这个名字我很喜欢！
Misaka 具有以下独有特性：
| 特性 | 说明 |
|---|---|
| 🔍 环境检查 | 启动时自动检测 Claude Code CLI、Node.js、Python、Git 是否已安装。缺失时提供一键安装，使用平台专属命令（winget/brew/apt）。 |
| 📦 版本检查 | 启动时自动检测 Claude Code CLI 是否有新版本，支持一键升级（npm install -g @anthropic-ai/claude-code@latest）。 |
| 🔀 Claude Code Router | 管理多套 API 配置（不同提供商、模型、Agent Team 模式），一键切换并写入 ~/.claude/settings.json。目前其他 GUI 均无此功能。 |
| 🖥️ 原生桌面 | 基于 Python + Flet（Flutter），非 Web 应用，以原生窗口运行。 |
| 🛡️ 权限控制 | 细粒度工具权限模式，在文件编辑或执行 shell 命令前弹出交互式审批对话框。 |
| 📚 技能管理 | 在应用内查看、从 ZIP 安装和刷新 Claude Code Skills（扩展）。 |
| 分类 | 详情 |
|---|---|
| 多模型对话 | 通过 /model 命令在 Claude Sonnet、Opus、Haiku 之间自由切换 |
| 流式响应 | 实时逐 token 渲染，支持随时中止，内置 Thinking 动画，中断后显示错误提示 |
| 会话管理 | 创建、重命名、删除、搜索对话会话 |
| 三种对话模式 | Code（编码）· Plan（规划）· Ask（问答）——下拉选择器 |
| 快捷命令发送 | /init 等命令可直接发送，无需先打开命令框 |
| 文件树浏览器 | 在右侧面板浏览项目目录，支持文件实时预览 |
| MCP 服务器支持 | 从 Claude 配置文件加载并管理 Model Context Protocol 服务器，支持删除确认、刷新及 HTTP 请求头配置 |
| 技能管理 | 在「技能」页面查看、从 ZIP 安装和刷新 Claude Code Skills |
| Claude Code Router | 多配置系统，管理不同的 API 提供商和模型预设 |
| 导入 CLI 会话 | 将 Claude Code CLI 的历史会话导入到 Misaka，支持分页加载与搜索 |
| 多语言界面 | English · 简体中文 · 繁體中文 |
| 主题切换 | 浅色 / 深色 / 跟随系统——重启后自动恢复，支持自定义强调色 |
| API 提供商配置 | 添加并管理多个 Anthropic API 提供商，支持自定义 Base URL |
| 权限控制 | 细粒度工具权限模式，支持交互式审批对话框 |
| 更新提醒 | 启动时自动检测 Claude Code CLI 是否有新版本 |
| 跨平台 | Windows · macOS |
| 开发者模式 | 支持热重载和调试日志，便于开发调试 |
| 分类 | 技术 |
|---|---|
| 语言 | Python 3.10+ |
| UI 框架 | Flet（基于 Flutter） |
| Claude 集成 | claude-agent-sdk |
| 运行时 | Node.js（Claude Code CLI） |
| 语法高亮 | Pygments |
| 图片处理 | Pillow |
| 文件监听 | watchdog |
| 异步 I/O | aiofiles · anyio |
- Python 3.10 及以上
- Node.js（用于 Claude Code CLI）
- Claude Code CLI — 通过 npm 安装：
npm install -g @anthropic-ai/claude-code
- Anthropic API Key — 通过环境变量设置，或在应用「设置」页面中配置
# 1. 克隆仓库
git clone https://github.com/knqiufan/Misaka.git
cd Misaka
# 2. 安装依赖
pip install -e ".[dev]"
# 3. 设置 API Key（或在「设置」页面中配置）
set ANTHROPIC_API_KEY=sk-ant-... # Windows
export ANTHROPIC_API_KEY=sk-ant-... # macOS / Linux
# 4. 启动 Misaka
misaka
# 或
python -m misaka.main应用窗口默认尺寸为 1280 × 860（最小 800 × 600）。所有数据——会话、设置、日志——均存储在 ~/.misaka/ 目录下。
在启动前设置环境变量，或在应用内「设置 → API 提供商」中添加：
export ANTHROPIC_API_KEY=sk-ant-...Claude Code Router 用于管理多套 API 配置，并可一键切换。
1. 添加配置
- 进入 设置 → Claude Code Router
- 点击 添加配置
- 填写：
- 提供商名称 — 如「Anthropic 官方」「自定义 API」
- API Key — 你的 Anthropic API 密钥
- 请求 URL — 默认留空，或填写自定义 Base URL
- 主模型 / Haiku / Opus / Sonnet 模型 — 各档位模型 ID
- Agent Team 模式 — 是否启用 Agent Teams 功能
2. 启用配置
- 在目标配置上点击 启用
- Misaka 会将配置写入
~/.claude/settings.json - Claude Code CLI 将使用该配置进行所有会话
3. 典型场景
- 在 Anthropic 官方 API 与第三方兼容端点之间切换
- 不同项目使用不同模型（如 Haiku 快速任务、Opus 复杂编码）
- 工作与个人 API Key 分开管理
MCP（Model Context Protocol）服务器可扩展 Claude Code 能力，例如连接数据库、API、文件系统等。
方式一：在 Misaka 界面中配置
- 从侧边栏打开 插件（MCP 服务器）
- 点击 添加服务器
- 选择 传输类型：
- stdio — 本地进程（如
npx -y @modelcontextprotocol/server-filesystem ~/Documents） - http — 远程 HTTP 端点（如
https://mcp.notion.com/mcp） - sse — 旧版 SSE 端点
- stdio — 本地进程（如
- stdio：填写 命令 和 参数（空格分隔）
- http/sse：填写 URL
- 点击 添加 — 配置会保存到
~/.claude.json或~/.claude/settings.json
方式二：通过配置文件编辑
编辑 ~/.claude.json 或 ~/.claude/settings.json：
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
},
"notion": {
"type": "http",
"url": "https://mcp.notion.com/mcp"
}
}
}保存后，在插件页面点击 重新加载配置。更多示例见 Claude Code MCP 文档。
Skills（Claude Code 扩展）是提供可复用指令与模板的 Markdown 文件。从侧边栏打开 技能 进行查看和管理。当前不支持在界面内创建和编辑技能，需手动在以下路径中添加 .md 文件。
技能来源
| 来源 | 路径 |
|---|---|
| 全局 | ~/.claude/commands/*.md — 全局可用 |
| 项目 | ./.claude/commands/*.md — 按项目生效 |
| 已安装 | ~/.claude/skills/*/SKILL.md 与 ~/.agents/skills/*/SKILL.md |
| 插件 | ~/.claude/plugins/marketplaces/*/plugins/*/commands/*.md |
1. 查看技能
- 从侧边栏打开 技能，技能按来源（全局、项目、已安装、插件）分组展示。
- 使用搜索框按名称或描述筛选。
2. 从 ZIP 安装
- 点击 从 ZIP 安装 并选择本地
.zip文件 - 压缩包需包含带
SKILL.md的目录，将解压到~/.claude/skills/<包名>/
3. 刷新
- 点击 刷新 可在手动修改文件后重新加载所有技能。
覆盖默认的 ~/.misaka/ 存储位置：
export MISAKA_DATA_DIR=/path/to/custom/dir# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
pytest
# 代码检查（Ruff）
ruff check misaka/
# 类型检查（mypy）
mypy misaka/
# 运行开发模式（热重载）
python -m misaka.main
# 或使用 flet run
flet run -m misaka.main -d -rpip install -e ".[build]"
pyinstaller misaka.spec打包后的可执行文件以 GUI 应用运行，不会弹出控制台窗口。在 Windows 上，子进程调用（如 Claude Code CLI）会被隐藏，避免控制台闪烁。
| 包名 | 用途 |
|---|---|
flet >= 0.27 |
基于 Flutter 的跨平台 UI 框架 |
claude-agent-sdk >= 0.1.5 |
官方 Claude Code Agent 集成 SDK |
Pygments >= 2.18 |
代码块语法高亮 |
watchdog >= 4.0 |
文件系统事件监听 |
aiofiles >= 24.0 |
异步文件 I/O |
anyio >= 4.0 |
异步并发原语 |
Pillow >= 10.0 |
图片处理与预览 |