vite-plugin-claude-dev-server

> Vite 插件 - 在浏览器中集成 Claude Code AI 助手终端，支持页面元素检查和源码定位


功能特性

- ttyd 终端 - 使用 ttyd 提供真正的 PTY 终端体验，完整支持 ANSI 转义序列、颜色、光标控制
- Claude Code 集成 - 通过 WebSocket 与后台 Claude Code 进程通信，实时 AI 辅助开发
- 元素检查器 - 点击页面元素，自动定位到对应源代码位置，并发送到 Claude Code 终端
- 智能提示格式 - 自动格式化选中元素为 @filename:line "text content" 格式
- CLI 工具 - 提供命令行工具快速检查 ttyd 安装和自动配置项目
- 快捷键支持 - Cmd/Ctrl + \\ 打开/关闭面板，Escape 退出检查模式
- 悬浮按钮 - Claude Code 图标按钮打开面板，Inspect 按钮进入检查模式

快速开始

$3

`bash


1. 检查 ttyd 是否已安装

npx vite-plugin-claude-dev-server check-ttyd

2. 自动配置到你的 Vite 项目

npx vite-plugin-claude-dev-server setup
`

CLI 会自动：
- 检测并安装 ttyd（如需要）
- 找到你的 vite.config.ts/js
- 添加插件到配置文件
- 安装到 devDependencies

$3

`bash
npm install vite-plugin-claude-dev-server -D
`

在 vite.config.ts 中添加插件：

`typescript
import { defineConfig } from 'vite'
import claudeDevServerPlugin from 'vite-plugin-claude-dev-server'

export default defineConfig({
plugins: [
claudeDevServerPlugin()
]
})
`

前置要求

$3

插件需要 ttyd 来提供终端功能：

macOS:
`bash
brew install ttyd
`

Linux:
`bash


Ubuntu/Debian

sudo apt install ttyd

或从源码编译

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

`

检查安装:
`bash
npx vite-plugin-claude-dev-server check-ttyd
`

使用方法

$3

页面右上角会显示两个悬浮按钮：

| 按钮 | 功能 |
|------|------|
| Claude Code 图标 | 打开/关闭 Claude Code 面板 |
| Inspect 图标 | 进入/退出元素检查模式 |

$3

| 快捷键 | 说明 |
|--------|------|
| Cmd/Ctrl + \\` | 打开/关闭 Claude Code 面板 |
| Escape | 退出检查模式或关闭面板 |

$3

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

提示格式说明

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

`
@: "text content"
`

- @filename:line - 源文件路径和行号（支持 React DevTools、Vue 组件）
- - CSS 选择器（标签名 + ID + 类名）
- "text content" - 元素文本内容（如果存在）

CLI 命令

$3

检查 ttyd 是否已正确安装：

`bash
npx vite-plugin-claude-dev-server check-ttyd
`

输出示例：
`
Checking ttyd installation...

✓ ttyd found in PATH

--- Summary ---
✓ ttyd is properly installed and accessible

You can use claude-dev-server with default settings.
`

$3

自动配置到你的 Vite 项目：

`bash
npx vite-plugin-claude-dev-server setup
`

会自动：
- 查找 vite.config.ts/js
- 添加 import 语句
- 在 plugins 数组中添加插件
- 检测包管理器并安装（npm/pnpm/yarn/bun）

配置选项

`typescript
import claudeDevServerPlugin from 'vite-plugin-claude-dev-server'

export default defineConfig({
plugins: [
claudeDevServerPlugin({
// WebSocket 服务器端口（自动分配）
port?: number

// Claude Code 可执行文件路径（默认 'claude'）
claudePath?: string

// 传递给 Claude Code 的额外参数
claudeArgs?: string[]
})
]
})
`

架构

`
┌─────────────────────────────┐ WebSocket ┌──────────────┐
│ Browser (ttyd) │ ◄─────────────────► │ Node Server │
│ │ │ │
│ - Floating Buttons │ │ - ttyd │
│ - Inspector Overlay │ │ - WebSocket │
│ - Terminal (xterm.js) │ │ - Claude CLI│
└─────────────────────────────┘ └──────────────┘
│
▼
┌──────────────┐
│ Claude Code │
│ Process │
└──────────────┘
`

元素源码定位

插件通过以下方式定位元素源码：

1. React DevTools - 优先使用 React 内部的 _debugSource 信息
2. Vue 组件 - 支持 Vue 的 __file 元数据
3. 项目根路径 - 自动从 Vite 配置获取项目根路径，生成相对路径

常见问题

$3

A: 通过 claudePath 配置指定路径：

`typescript
claudeDevServerPlugin({
claudePath: '/path/to/your/claude'
})
`

$3

A: Dev Tools 自身的元素（悬浮按钮、面板等）已被排除，无法选中。

$3

A: 目前支持 React、Vue。使用项目根路径自动计算相对路径。

$3

A: 是的，插件需要 ttyd 来提供真正的 PTY 终端体验。使用 check-ttyd 命令检查安装状态。

开发

`bash


安装依赖

npm install

构建

npm run build

监听模式

npm run dev

运行示例

cd examples/vite-app
npm install
npm run dev
``

技术栈

- Vite Plugin API - 插件开发和脚本注入
- ttyd - 终端 over HTTP/WebSocket
- xterm.js - Web 终端组件（VS Code 同款）
- WebSocket (ws) - 客户端-服务器通信
- Commander.js - CLI 命令行工具

License

MIT