claude-dev-server

通用开发服务器包装器 - 在浏览器中集成 Claude Code AI 助手终端，支持 Vite、Next.js、Webpack 等所有开发服务器

功能特性

• 通用支持 - 适用于 Vite、Next.js、Webpack 或任何 dev server
• 分屏布局 - 左侧 Claude Code 终端，右侧开发服务器，可拖动分隔线调整宽度
• ttyd 终端 - 使用 ttyd 提供真正的 PTY 终端体验，完整支持 ANSI 转义序列、颜色、光标控制
• Claude Code 集成 - 通过 WebSocket 与后台 Claude Code 进程通信，实时 AI 辅助开发
• 元素检查器 - 点击页面元素，自动定位到对应源代码位置，并发送到 Claude Code 终端
• 智能提示格式 - 自动格式化选中元素为 @filename:line <selector> "text content" 格式
• Next.js 路由支持 - 使用真实 iframe src 解决 Next.js 路由问题
• 无需安装 - 直接使用 npx 运行，自动检测项目类型
• 快捷键支持 - Cmd/Ctrl + Shift + I 切换检查模式，Escape 退出

快速开始

前置要求

需要安装 ttyd：

macOS:

brew install ttyd

Linux:

# Ubuntu/Debian
sudo apt install ttyd

# 或从源码编译
# 见 https://tsl0922.github.io/ttyd/

使用方法

在任意项目目录下运行：

# 默认端口 3000
npx claude-dev-server@latest

# 指定端口
npx claude-dev-server@latest --port 4000

就这么简单！工具会：

1. 自动检测项目类型（Vite/Next/Webpack/Custom）
2. 启动对应的 dev server
3. 自动检测端口号（从 stdout 解析）
4. 启动 Claude Code 集成服务器
5. 打开浏览器即可使用

CLI 选项

| 选项 | 说明 | 默认值 | |------|------|--------| | -p, --port <port> | 代理服务器端口 | 3000 | | -h, --help | 显示帮助信息 | - |

使用方法

界面布局

浏览器打开后会显示分屏布局：

┌─────────────────────────────────────────────────────────────┐
│  ┌────────────────────┐ │ ┌──────────────────────────────┐  │
│  │  Claude Code 终端   │ │ │     开发服务器 (Next.js)      │  │
│  │                    │ │ │                              │  │
│  │  [Inspect 按钮]    │ ╳ │                              │  │
│  │                    │ │ │                              │  │
│  └────────────────────┘ │ └──────────────────────────────┘  │
│           左侧 (40%)      │           右侧 (60%)              │
└─────────────────────────────────────────────────────────────┘

• 左侧面板 - Claude Code 终端（可拖动分隔线调整宽度）
• 右侧面板 - 开发服务器（Next.js/Vite/Webpack 应用）
• 分隔线 - 鼠标悬停变橙色，拖动可调整左右宽度

键盘快捷键

| 快捷键 | 说明 | |--------|--------| | Cmd/Ctrl + Shift + I | 切换元素检查模式 | | Escape | 退出检查模式 |

工作流程

1. 在左侧 Claude Code 终端中与 AI 交互
2. 点击左上角的 Inspect 按钮进入检查模式
3. 鼠标移动到右侧页面元素上会高亮显示
4. 点击元素后自动发送格式化提示到终端：

   @src/App.tsx:12 <button.inline-flex.items-center> "Submit"

5. Claude Code 会根据代码位置上下文回答你的问题

提示格式说明

选中元素后，会自动生成以下格式的提示：

@<filename> <selector> "text content"

• @filename - 源文件路径
• <selector> - CSS 选择器（标签名 + ID + 类名，最多 3 个）
• "text content" - 元素文本内容（前 50 个字符）

示例：

@apps/web/src/app/[lng]/login/page.tsx <button.inline-flex.items-center> "Log In"

架构

Next.js 路由解决方案

使用 dev.html + referer 检测解决 Next.js 在 iframe 中的路由问题：

浏览器直接访问: http://localhost:3000/dashboard
         ↓
服务器检测: 无 dev.html referer
         ↓
302 重定向到: /dev.html?path=/dashboard
         ↓
dev.html 加载，创建 iframe src="/dashboard"
         ↓
iframe 加载，referer=".../dev.html"
         ↓
服务器检测到 dev.html referer
         ↓
代理原始 HTML（无注入）
         ↓
Next.js 有真实 window.location → 路由正常工作 ✅

系统架构

┌─────────────────────────────────────────────────────────────┐
│                  Claude Dev Server (主进程)                  │
│                                                              │
│  ┌──────────────────┐         ┌──────────────────┐         │
│  │  HTTP Proxy      │         │  Control Server  │         │
│  │  (Port :3000)    │         │  (WebSocket)     │         │
│  │                  │         │                  │         │
│  │  - Referer 检测   │         │  - ttyd 管理      │         │
│  │  - dev.html 重定向│◄───────►│  - Claude 进程   │         │
│  │  - 代理转发       │         │                  │         │
│  └────────┬─────────┘         └──────────────────┘         │
│           │                                                    │
│           ▼                                                    │
│  ┌──────────────────┐                                        │
│  │  Target Server   │                                        │
│  │  (Auto detected) │                                        │
│  │                  │                                        │
│  │  Vite / Next     │                                        │
│  │  Webpack / etc   │                                        │
│  └──────────────────┘                                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │   Browser       │
                    │                 │
                    │  ┌───────────┐  │
                    │  │ dev.html  │  │
                    │  │ (分屏布局) │  │
                    │  │           │  │
                    │  │ 左: 终端  │  │
                    │  │ 右: iframe│  │
                    │  └───────────┘  │
                    └─────────────────┘

支持的项目类型

| 类型 | 检测文件 | 默认命令 | |------|----------|----------| | Vite | vite.config.ts/js | npm run dev | | Next.js | next.config.js/mjs | npm run dev | | Webpack | webpack.config.ts/js | npm run dev | | Custom | - | npm run dev |

常见问题

Q: 如何使用自己的 claude 命令？

A: 暂不支持，默认使用 claude 命令。

Q: Inspect 模式下为什么有些元素无法选中？

A: 某些特殊元素（如 iframe 内部）可能无法正常选中。

Q: 支持哪些框架的源码定位？

A: 目前支持 Next.js (通过 Turbopack chunk 解析)。其他框架使用默认的元素选择器。

Q: 可以在其他端口使用吗？

A: 可以，使用 --port 选项指定任意端口。

Q: 为什么 URL 中有 /dev.html?path=...？

A: 这是正常的。dev.html 是分屏布局容器，path 参数指定右侧 iframe 要加载的实际路径。

技术栈

• HTTP Proxy - 请求转发和 referer 检测
• dev.html - 分屏布局容器，解决 Next.js 路由问题
• ttyd - 终端 over HTTP/WebSocket
• xterm.js - Web 终端组件（VS Code 同款）
• WebSocket (ws) - 客户端-服务器通信

License

MIT