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 "text content" 格式
- Next.js 路由支持 - 使用真实 iframe src 解决 Next.js 路由问题
- 无需安装 - 直接使用 npx 运行，自动检测项目类型
- 快捷键支持 - Cmd/Ctrl + Shift + I 切换检查模式，Escape 退出

快速开始

$3

需要安装 ttyd：

macOS:
``bash
brew install ttyd
`

Linux:
`bash


Ubuntu/Debian

sudo apt install ttyd

或从源码编译

见 https://tsl0922.github.io/ttyd/

`

$3

在任意项目目录下运行：

`bash


默认端口 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 | 代理服务器端口 | 3000 |
| -h, --help | 显示帮助信息 | - |

使用方法

$3

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

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

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

$3

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

$3

1. 在左侧 Claude Code 终端中与 AI 交互
2. 点击左上角的 Inspect 按钮进入检查模式
3. 鼠标移动到右侧页面元素上会高亮显示
4. 点击元素后自动发送格式化提示到终端：
`
@src/App.tsx:12 "Submit"
`
5. Claude Code 会根据代码位置上下文回答你的问题

提示格式说明

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

`
@ "text content"
`

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

示例：
`
@apps/web/src/app/[lng]/login/page.tsx "Log In"
`

架构

$3

使用 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 → 路由正常工作 ✅
`

$3

`
┌─────────────────────────────────────────────────────────────┐
│ 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 |

常见问题

$3

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

$3

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

$3

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

$3

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

$3

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