vite-plugin-claude-dev-server

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

功能特性

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

快速开始

方法一：使用 CLI 自动配置（推荐）

# 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

方法二：手动安装

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

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

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

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

前置要求

ttyd 安装

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

macOS:

brew install ttyd

Linux:

# Ubuntu/Debian
sudo apt install ttyd

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

检查安装:

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

使用方法

悬浮按钮

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

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

键盘快捷键

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

工作流程

1. 按 `Cmd/Ctrl + \`` 或点击 Claude Code 图标打开面板
2. 在终端中直接与 Claude Code 交互
3. 点击 Inspect 按钮进入检查模式
4. 鼠标移动到页面元素上会高亮显示
5. 点击元素后自动发送格式化提示到终端：

   @src/App.tsx:12 <button className="btn"> "Submit"

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

提示格式说明

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

@<filename>:<line> <selector> "text content"

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

CLI 命令

check-ttyd

检查 ttyd 是否已正确安装：

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.

setup

自动配置到你的 Vite 项目：

npx vite-plugin-claude-dev-server setup

会自动：

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

配置选项

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 配置获取项目根路径，生成相对路径

常见问题

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

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

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

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

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

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

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

Q: ttyd 必须安装吗？

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

开发

# 安装依赖
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