Vibeyard 阅读分析与使用笔记

这篇文章解决什么问题

Vibeyard 是一个面向 AI coding agents 的桌面 IDE，仓库地址：

elirantutia/vibeyard

它不是新的模型，也不是 VS Code 插件。更准确地说，它是在本地桌面应用里管理多个 AI CLI 会话：Claude Code、Codex CLI、Gemini CLI，以及源码里已经接入的 GitHub Copilot CLI。

它解决的是“多个 AI 终端会话难管理”的问题：

多个 agent 会话并行跑。
每个项目有独立 dashboard 和 kanban。
从任务卡片启动或恢复 CLI 会话。
记录 session 状态、成本、上下文窗口、工具调用。
内嵌浏览器，把 DOM 选择器、页面 URL、截图或操作流程发给 agent。
通过 hook 把不同 CLI 的运行状态接回 Vibeyard。

采集时间：2026-06-12。

阅读对象：GitHub main 分支 tarball、README.md、HOOKS.md、package.json、主进程、provider、hook、readiness、sharing、browser-tab 等源码。

说明：本文未本地安装、未运行 npm start、未执行测试。

先说结论

Vibeyard 的核心价值是把“AI CLI 终端”变成“可管理的项目工作台”。
它最适合同时使用多个 agent、多个项目、多个长会话的人。
它不是替代 Claude Code / Codex / Gemini，而是给这些 CLI 加一层桌面壳、会话管理和项目上下文面板。
它的强项是 terminal-centric：PTY、tab、split、swarm、kanban、session resume、inspector 都围绕本地 CLI。
它的风险也来自这里：需要改写各 CLI 的 hook / statusLine / settings，和现有个人配置可能冲突。
README 写支持 Claude Code、Codex CLI、Gemini CLI；源码 providers/registry.ts 里还注册了 Copilot provider。
README 写 npm 支持 macOS、Linux、Windows，但 bin/vibeyard.js 当前直接限制 npm launcher 只支持 macOS 和 Windows；Linux 需要下载 release。
项目还在快速迭代，package.json 版本是 0.3.1，CHANGELOG 里 0.2.x 到 0.3.x 的 UI、kanban、readiness、profile、browser 能力变化很密集。

我的判断：

Vibeyard 更像“AI CLI 多会话调度台”，不是“帮 agent 变聪明”的 prompt 框架。

它适合谁

使用者	适合程度	原因
同时跑多个 Claude/Codex/Gemini 会话的开发者	很适合	终端、状态、成本、上下文、恢复都集中管理
经常让 agent 做 PR review、修 bug、改页面的人	很适合	kanban、GitHub widget、浏览器 inspect 能把任务入口收起来
团队内需要共享 agent 会话的人	适合	有 WebRTC P2P session sharing，支持只读和读写
只偶尔用一次 CLI 的用户	一般	桌面壳和 hook 配置成本可能超过收益
对本机 CLI 配置很敏感的人	谨慎	会安装 hooks、statusLine，并读取/写入不同 provider 的配置
想要云端托管 agent 平台的人	不适合	它本质是本地 Electron + 本地 CLI + 本地 PTY

基本使用方法

1. 先安装至少一个 AI CLI

Vibeyard 启动时会检查 provider。如果 Claude、Codex、Gemini、Copilot 都不可用，主进程会弹错误并退出。

至少准备一个：

Claude Code
OpenAI Codex CLI
Gemini CLI
GitHub Copilot CLI（源码已有 provider）

这些 CLI 需要先在本机完成登录或鉴权。Vibeyard 不替你买模型额度，也不替你创建 provider 账号。

2. 安装 Vibeyard

官方 README 给了几种方式。

macOS：

到 GitHub Releases 下载最新 .dmg。
拖到 Applications。
启动。

Linux：

bash

sudo dpkg -i vibeyard_*.deb

或：

bash

chmod +x Vibeyard-*.AppImage
./Vibeyard-*.AppImage

Windows：

下载 Setup .exe 或 portable .exe。
安装或直接运行。

npm：

bash

npm i -g vibeyard
vibeyard

注意：README 说 npm 支持 macOS、Linux、Windows，但当前 bin/vibeyard.js 对 Linux 会输出：

text

The npm launcher currently supports macOS and Windows.
For Linux, download from: https://github.com/elirantutia/vibeyard/releases

所以 Linux 上更稳的方式是 release 包。

3. 添加项目

启动后把本地代码仓库加入 Vibeyard。它会围绕项目创建 overview、session、kanban、file tree、Git、readiness 等视图。

建议第一次先用一个非关键项目试：

添加项目目录。
打开 overview。
看 AI Readiness Score。
新建一个 Claude/Codex/Gemini session。
确认 CLI 能正常启动、输入、退出、恢复。

不要一上来就在核心仓库里点所有自动修复。先看它准备改什么。

4. 从 kanban 管任务

Vibeyard 的 kanban 是 per-project 的。一个卡片可以带 prompt、notes、provider、plan mode、tags。

典型流程：

在 kanban 新建任务卡片。
写清楚目标和约束。
从卡片启动 AI CLI session。
会话完成后，卡片自动或手动流转到 Done。
后续从卡片恢复同一个 session。

这比直接开一堆终端更适合多任务并行，因为任务、会话和状态绑定在同一个项目里。

5. 用浏览器 tab 辅助前端修改

README 重点宣传了 embedded browser tab。源码里可以看到几种交互：

选择 DOM 元素后生成 prompt。
记录页面流程后生成 prompt。
截图并把图片路径放进 prompt。
发送到新 session 或已有 session。

适合这类工作：

打开 localhost:3000。
inspect 某个按钮或表单。
写一句“把这个按钮弱化”“修复这个布局错位”。
把 DOM selector、text、URL 一起交给 agent。

这比只发截图更准确，因为 agent 同时拿到页面上下文和选择器。

核心功能拆解

多 provider 会话

源码里 provider 抽象在 src/main/providers/provider.ts，注册入口在 src/main/providers/registry.ts。

当前 provider：

Provider	CLI	关键能力
ClaudeProvider	`claude`	session resume、cost tracking、context window、hook status、system prompt injection、profile
CodexProvider	`codex`	session resume、hook status、config reading、system prompt injection
GeminiProvider	`gemini`	session resume、hook status、config reading、plan mode
CopilotProvider	`copilot`	session resume、hook status、config reading、plan mode

不同 provider 能力不等价。比如成本和上下文窗口只有 Claude provider 标成 true；Codex、Gemini、Copilot 主要是 session 和 hook 状态。

PTY 会话管理

Vibeyard 通过 node-pty 启动真实 CLI。spawnPty 做几件事：

注册 session。
给 provider 注入环境变量。
拼 provider 的启动参数。
处理 resume、initial prompt、system prompt、extra args。
在 macOS / Windows 上补全 PATH。
对 Windows .cmd、.bat、.ps1 做 shell 包装。
PTY 已退出时保护 write/resize/kill，避免单个坏会话拖垮主进程。

这说明 Vibeyard 不是模拟终端 UI，而是实打实管理本地 CLI 进程。

Hook 和状态同步

HOOKS.md 把会话状态映射得很清楚：

Hook Event	Session Status
`SessionStart`	`waiting`
`UserPromptSubmit`	`working`
`PostToolUse`	`working`
`PostToolUseFailure`	`working`
`Stop`	`completed`
`StopFailure`	`waiting`
`PermissionRequest`	`input`

大致链路是：

text

CLI hook
-> /tmp/vibeyard/<sessionId>.status
-> main process watch
-> IPC
-> renderer session state

另外还会写：

文件	用途
`.status`	当前会话状态
`.sessionid`	CLI 原生 session id，用于 resume
`.cost`	成本、tokens、context window
`.toolfailure`	工具失败信息
`.events`	inspector timeline

这套设计的好处是跨 CLI 统一状态；缺点是它依赖每个 CLI 的 hook 能力和配置格式。

AI Readiness Score

Readiness 分三类：

类别	权重
Instructions	50%
Context	30%
Optimizations	20%

它会检查：

是否有 CLAUDE.md、AGENTS.md、GEMINI.md 等指令文件。
指令文件是否过大。
是否有 .claudeignore。
是否有敏感文件可能进上下文。
是否有超过 1000 行的大文件。
是否需要 .vibeyardignore 过滤扫描。

这里要注意一个副作用：context-optimization.ts 里如果项目没有 .vibeyardignore，会尝试创建一个默认文件。这个行为对工具本身合理，但对代码仓库会产生新增文件。

Session inspector

Session inspector 读取事件流，展示：

时间线。
成本拆分。
token 使用。
工具调用统计。
上下文窗口。
tool failure。

这类信息对“agent 卡在哪一步”“到底烧了多少 token”“哪个工具失败了”很有用。

源码里 sharing 在 src/renderer/sharing/。它用 WebRTC 做点对点共享，支持：

host 分享本地 terminal session。
guest 加入远程 session。
read-only / read-write 模式。
passphrase / PIN 认证。
断开后清理 remote terminal pane。

适合团队临时协作看同一个 agent 会话。它不是云端团队平台，本质还是两端之间建立 P2P 连接。

Claude profiles

CHANGELOG 0.3.1 加了 Claude profiles。源码里 Claude provider 支持 CLAUDE_CONFIG_DIR，可以给不同 profile 用独立配置目录。

价值：

工作账号和个人账号分开。
credentials、settings、history 不混。
session resume 能带回对应 profile。

限制：

当前 profile 主要围绕 Claude provider。
macOS 上旧版 Claude Code 如果 keychain 隔离有问题，Vibeyard 会阻止启动 profile session，避免账号串用。

优点

1. 把多会话从终端里解放出来

裸终端跑多个 agent 很快会乱：

哪个在工作？
哪个在等权限？
哪个已经完成？
哪个项目对应哪个会话？
成本和上下文用了多少？

Vibeyard 用 tab、split、swarm、status dot、inspector、kanban 把这些信息集中起来。这是它最实在的价值。

2. 仍然尊重 CLI 原生能力

它没有自己造一个 agent runtime，而是继续调用本地 CLI：

Claude 还是 Claude Code。
Codex 还是 Codex CLI。
Gemini 还是 Gemini CLI。
Copilot 还是 Copilot CLI。

这让它能跟随 CLI 生态更新，也降低了“平台锁死”的问题。

3. 项目级 dashboard 比单会话更有用

一个 AI session 只能看到一次对话。项目 dashboard 可以放：

readiness。
kanban。
team。
sessions。
provider tools。
GitHub PR/Issue。
top files by tokens。

这让 AI 工作从“单次聊天”更接近“项目运维面板”。

4. Browser tab 对前端开发有直接价值

DOM inspect、flow recording、draw/screenshot 这些能力很适合前端修 UI。它把页面证据、选择器和用户意图一起交给 agent，比口头描述更稳。

5. Hook 状态模型比较清楚

HOOKS.md 把状态事件、状态机、文件副产物都写出来了。后续如果状态显示不准，可以沿着：

text

CLI hook -> /tmp/vibeyard -> watcher -> IPC -> renderer

逐段排查。

6. 兼顾个人和团队使用

个人侧有：

session resume。
favorite sessions。
global session search。
Claude profiles。
readiness quick wins。

团队侧有：

P2P sharing。
team personas。
GitHub widgets。
install-as-agent。

功能不是只服务单人玩具场景。

缺点和风险

1. 对本机配置侵入性不低

它要安装 hooks、statusLine、provider 配置：

Claude 写 ~/.claude/settings.json。
Codex 写 ~/.codex/config.toml 和 ~/.codex/hooks.json。
Gemini 写 ~/.gemini/settings.json。
Copilot 写项目内 .github/hooks/vibeyard-copilot-hooks.json。

Claude 有 settings-guard 检测 foreign statusLine 并弹窗确认，但整体仍然是会动本机 AI CLI 配置的工具。

建议第一次使用前备份相关配置。

2. 不同 provider 能力不一致

README 容易让人以为所有 provider 都同样完整。源码实际不是：

Claude 有 cost/context。
Codex 没有 cost/context。
Gemini 没有 system prompt injection。
Copilot hook 是项目级 .github/hooks。

所以不要把 Claude 下看到的体验直接套到所有 provider。

3. npm 安装说明和源码行为不完全一致

README 写 npm 支持 macOS、Linux、Windows；但 npm launcher 代码当前限制 Linux：

text

The npm launcher currently supports macOS and Windows.

Linux 用户应优先按 release 的 .deb 或 AppImage 路径走。

4. Electron + 多 PTY + watcher 复杂度高

它同时管理：

Electron 主进程和渲染器。
多个 PTY。
文件 watcher。
Git watcher。
provider config watcher。
hook status watcher。
WebRTC sharing。
xterm 渲染。

功能强，但故障面也大。遇到状态不同步、窗口卡顿、watcher 风暴、CLI 配置冲突时，排查成本不会低。

5. 自动 quick fix 要谨慎点

AI Readiness 的 Fix 会开新 session 并把 fix prompt 丢给 agent。这个设计方便，但不等于改动一定合理。

尤其是：

自动创建 .vibeyardignore。
建议拆大文件。
建议创建 ignore 文件。
建议改 AI instruction 文件。

这些都可能影响仓库工作流。建议先读 prompt，再决定是否执行。

6. 项目仍处早期快速变化

CHANGELOG.md 显示近期版本频繁加入或重构：

kanban。
overview widgets。
team tab。
readiness。
browser tab。
session inspector。
profiles。
UI restyle。

这说明项目活跃，但也意味着文档、README、源码行为可能短期漂移。

和其他 AI 工作流工具的区别

工具类型	代表	Vibeyard 的区别
单 CLI	Claude Code / Codex CLI / Gemini CLI	Vibeyard 管它们，不替代它们
Prompt / workflow 框架	Trellis / Superpowers	Vibeyard 更偏运行时 UI 和会话管理
IDE 插件	Cursor / VS Code 插件	Vibeyard 是独立桌面应用，terminal-centric
云端 agent 平台	Devin 类工具	Vibeyard 主要跑本地 CLI，不是云端托管 worker

如果你的痛点是“agent 不按团队流程做事”，Trellis 这类 repo workflow 更直接。

如果你的痛点是“会话太多、终端太乱、状态不可见”，Vibeyard 更直接。

落地前检查清单

使用前建议先确认：

已安装并登录至少一个 AI CLI。
备份 ~/.claude/settings.json、~/.codex/config.toml、~/.codex/hooks.json、~/.gemini/settings.json。
明确是否接受 Vibeyard 写 hook/statusLine。
Linux 不走 npm launcher，优先 release 包。
核心仓库里先不要直接点 readiness quick fix。
如果项目已经有 .github/hooks，先确认 Copilot hook 不会冲突。
团队共享时默认只读。

适合沉淀到本项目的点

这个仓库本身也给 AI 工具设计提供了几个参考：

Provider 抽象要显式声明能力，不要假设所有 CLI 一样。
会话状态最好有状态机文档，不要只靠 UI 颜色猜。
Hook 安装必须有冲突检测和用户确认，尤其是 statusLine 这类全局配置。
上下文优化工具不应该静默改用户仓库，至少要让改动可见。
前端 AI 修改最好带 DOM selector、URL、截图或流程记录，不只发自然语言。

Vibeyard 阅读分析与使用笔记 ​

这篇文章解决什么问题 ​

先说结论 ​

它适合谁 ​

基本使用方法 ​

1. 先安装至少一个 AI CLI ​

2. 安装 Vibeyard ​

3. 添加项目 ​

4. 从 kanban 管任务 ​

5. 用浏览器 tab 辅助前端修改 ​

核心功能拆解 ​

多 provider 会话 ​

PTY 会话管理 ​

Hook 和状态同步 ​

AI Readiness Score ​

Session inspector ​

P2P session sharing ​

Claude profiles ​

优点 ​

1. 把多会话从终端里解放出来 ​

2. 仍然尊重 CLI 原生能力 ​

3. 项目级 dashboard 比单会话更有用 ​

4. Browser tab 对前端开发有直接价值 ​

5. Hook 状态模型比较清楚 ​

6. 兼顾个人和团队使用 ​

缺点和风险 ​

1. 对本机配置侵入性不低 ​

2. 不同 provider 能力不一致 ​

3. npm 安装说明和源码行为不完全一致 ​

4. Electron + 多 PTY + watcher 复杂度高 ​

5. 自动 quick fix 要谨慎点 ​

6. 项目仍处早期快速变化 ​

推荐使用姿势 ​

个人开发 ​

前端项目 ​

多账号 Claude ​

团队协作 ​

和其他 AI 工作流工具的区别 ​

落地前检查清单 ​

适合沉淀到本项目的点 ​

参考链接 ​

Vibeyard 阅读分析与使用笔记

这篇文章解决什么问题

先说结论

它适合谁

基本使用方法

1. 先安装至少一个 AI CLI

2. 安装 Vibeyard

3. 添加项目

4. 从 kanban 管任务

5. 用浏览器 tab 辅助前端修改

核心功能拆解

多 provider 会话

PTY 会话管理

Hook 和状态同步

AI Readiness Score

Session inspector

P2P session sharing

Claude profiles

优点

1. 把多会话从终端里解放出来

2. 仍然尊重 CLI 原生能力

3. 项目级 dashboard 比单会话更有用

4. Browser tab 对前端开发有直接价值

5. Hook 状态模型比较清楚

6. 兼顾个人和团队使用

缺点和风险

1. 对本机配置侵入性不低

2. 不同 provider 能力不一致

3. npm 安装说明和源码行为不完全一致

4. Electron + 多 PTY + watcher 复杂度高

5. 自动 quick fix 要谨慎点

6. 项目仍处早期快速变化

推荐使用姿势

个人开发

前端项目

多账号 Claude

团队协作

和其他 AI 工作流工具的区别

落地前检查清单

适合沉淀到本项目的点

参考链接