vibego - 通过 telegram 随时随地的进行 vibe coding
通过 Telegram 随时随地驱动你的终端 AI CLI（支持 Codex / ClaudeCode / Gemini / Copilot）
For the english version, see README-en.
功能介绍
- 通过 Telegram 随时随地驱动你的终端 AI CLI;
- 通过 telegram 做到简单的任务管理与缺陷报告，可在 Telegram 中直接记录并追踪；
- 通过 telegram 随时在 Codex / ClaudeCode / Gemini / Copilot 终端 CLI 间一键切换；
- 通过 Telegram Bot API 的 HTTPS 请求通道传输指令到 CLI，链路全程由 TLS 加密保护。
- 运行期日志和状态文件统一写入本机 ~/.config/vibego/，敏感数据不出终端；
环境依赖
终端环境安装且登录了 codex / claudeCode / gemini / copilot（按需）
brew install python@3.11 tmux
brew install pipx
python3 -m venv ~/.config/vibego/runtime/venv
source ~/.config/vibego/runtime/venv/bin/activate
- 最低需要 Python 3.9，推荐 3.11+；根据 datetime 官方文档，
datetime.UTC仅在 3.11+ 中提供，本仓库已通过timezone.utc兜底兼容更早版本。 scripts/run_bot.sh会在启动时自动优先选择可用的python3.11（可通过VIBEGO_PYTHON_BIN覆盖），并在找不到 3.11 时回退到系统python3但确保版本 ≥3.9。
快速开始
创建并获取 telegram bot token
建议通过 PyPI 安装的 vibego 命令完成初始化与启动，示例：
- 首次创建 Token 可参考 Telegram 官方 BotFather 指南（https://core.telegram.org/bots#botfather）：
- 在 Telegram 客户端搜索
@BotFather并开始对话； - 发送
/start，然后依次发送/newbot，根据提示输入机器人名称与用户名； - BotFather 将返回以
123456789:ABC...形式的 HTTP API Token，请妥善保存； - 若需重新获取或重置 Token，可在同一对话中发送
/token，选择目标机器人后领取新令牌。
- 在 Telegram 客户端搜索
安装 & 启动 vibego
执行该步骤之前，确保您的终端已经安装并登录了 codex / claudeCode / gemini / copilot（按需），且已经准备好了 telegram bot token。
demo启动脚本会在运行前自动把仓库根目录的 AGENTS-template.md 写入$HOME/.codex/AGENTS.md/$HOME/.claude/CLAUDE.md的<!-- vibego-agents:start -->...<!-- vibego-agents:end -->区块；若文件原本不存在会直接创建，存在则保留你已有内容并备份为.vibego.bak，方便进一步自定义
pipx install vibego # 或者 pip install --user vibego
vibego init # 初始化配置目录并写入 Master Bot Token
vibego start # 启动 master 服务
然后在 telegram 创建的 bot中点击/statr，enjoy it！
Codex Skill / Plugin 与 vibe-diagram
vibego 会随 agents-sync 同步内置 vibe-diagram skill；同时仓库也提供 plugins/vibe-diagram，可作为 Codex plugin / repo
marketplace 分发给其他人使用。
触发边界
vibe-diagram只在明确要求画图、图形化、HTML 图，或答案需要说明一个实现对象如何在系统中产生、流转、转换并影响结果时自动使用。- 当问题需要呈现跨角色/模块的因果、时序、状态、数据、证据、前后差异或验收关系时，默认生成单文件 HTML 图。
- “为什么 / 怎么做”按意图区分：概念解释、安装升级、轻量用法说明默认简洁文本；行为成因、故障成因和逻辑链路理解默认生成 HTML 图。
- 若纯文本回答会退化成路径、函数、字段或证据 bullet 清单，必须改成图；不要把关键词堆成触发条件。
- 只在一个短句即可讲清的定义、翻译改写、简单命令、轻量取舍或用户明确不要图时默认使用简洁文本。
- HTML 顶部 tabs / role=tablist 只用于同一图型的多个候选布局；不得把追问、步骤、发布说明或普通章节导航追加成按钮。
本机同步 / 更新
pipx upgrade vibego
vibego agents-sync --json
agents-sync 会更新 AGENTS 目标文件，并把内置 skill 同步到本机 native skill 目录（如 ~/.codex/skills/vibe-diagram 与
~/.agents/skills/vibe-diagram）。长期运行的 Codex / worker 若需要立即读取新 skill，建议重启对应进程。
通过 repo marketplace 安装 / 升级 plugin
codex plugin marketplace add /path/to/vibego
codex plugin add vibe-diagram@vibego
上游更新后，已安装用户需要手动刷新/重装：
codex plugin marketplace upgrade vibego
codex plugin add vibe-diagram@vibego
native skill 是本机能力目录；plugin 是 Codex 可安装/分发单位。Superpowers 这类能力通常以 plugin 分发，plugin 内部再包含多个 skills。
vibe-diagram同时支持本机 native skill 同步和 repo marketplace plugin 分发。
目录结构
bot.py：aiogram 3 worker，支持多模型会话解析（Codex / ClaudeCode / Gemini / Copilot）。scripts/run_bot.sh：一键启动脚本（自动建 venv、启动 tmux + 模型 CLI + bot）。scripts/stop_bot.sh：终止当前项目 worker（tmux + bot 进程）。scripts/start_tmux_codex.sh：底层 tmux/CLI 启动器，被run_bot.sh调用，默认以tmux -u强制启用 UTF-8。scripts/models/：模型配置模块（common.sh/codex.sh/claudecode.sh/gemini.sh/copilot.sh）。logs/<model>/<project>/：运行日志（run_bot.log、model.log、bot.pid、current_session.txt），默认位于~/.config/vibego/logs/。model.log由scripts/log_writer.py控制，单文件上限 20MB，仅保留最近 24 小时的归档（可通过MODEL_LOG_MAX_BYTES、MODEL_LOG_RETENTION_SECONDS覆盖）。
.env.example：环境配置模板（复制为.env后按需修改）。
Spec-Driven Development（speckit）工作流（实验）
vibego 仓库内包含 .specify/ 脚本与模板，可用于按 Spec-Driven Development 的节奏产出可审阅的规格/计划/任务，
再进入实现阶段；用于降低“纯 vibe coding”带来的不确定性。
参考入口（本仓库样例，绝对路径可复核）：
- 评估结论：
/Users/david/hypha/tools/vibego/specs/001-speckit-feasibility/assessment-report.md - 快速复现与演示：
/Users/david/hypha/tools/vibego/specs/001-speckit-feasibility/quickstart.md
上游参考（官方）：
- Spec Kit：https://github.com/github/spec-kit
- SDD 流程说明：https://raw.githubusercontent.com/github/spec-kit/main/spec-driven.md
安全边界提醒（必读）：
- 不要在任何文档/日志/报错中粘贴真实 token、chat_id 或用户标识；示例请使用占位符。
- 运行期日志/状态文件必须写入
~/.config/vibego/（或由VIBEGO_CONFIG_DIR/MASTER_CONFIG_ROOT覆盖），不要落入仓库。
日志 & 目录
~/.config/vibego/logs/
└─ codex/
└─ mall-backend/
├─ run_bot.log # run_bot.sh 输出
├─ model.log # tmux pipe-pane 捕获的模型 CLI 输出
├─ bot.pid # 当前 bot 进程 PID（stop_bot.sh 使用）
└─ current_session.txt # 最近一次 JSONL 会话指针
从 2025 年起，所有日志、数据库、状态文件默认写入
~/.config/vibego/；scripts/migrate_runtime.sh可将旧版本在仓库内生成的运行期文件一次性迁移到该目录。
模型切换
- 支持参数：
codex、claudecode、gemini、copilot。 - 切换流程：
stop_bot.sh --model <旧>→run_bot.sh --model <新>。 - 每个模型在
scripts/models/<model>.sh中维护独立配置，互不依赖；公共逻辑位于scripts/models/common.sh。 ACTIVE_MODEL会在/start回复及日志中显示，并写入环境变量供bot.py使用。
Codex
| 变量 | 说明 |
|---|---|
CODEX_WORKDIR |
Codex CLI 工作目录（默认 .env 中自定义或 fallback ROOT） |
CODEX_CMD |
启动命令，默认 codex --dangerously-bypass-... |
CODEX_GOALS_ENABLED |
是否启动时追加 -c features.goals=true；默认 1，设为 0/false/no/off 可关闭实验性 /goal |
CODEX_SESSION_ROOT |
JSONL 根目录（默认 ~/.codex/sessions） |
CODEX_SESSION_GLOB |
JSONL 文件匹配（默认 rollout-*.jsonl） |
Telegram worker 侧支持 Codex /goal [objective|pause|resume|clear]。裸 /goal 会打开轻量管理面板；
带参数的 /goal <objective|pause|resume|clear> 会直接透传给 Codex。Goal 的真实状态以 Codex active
thread 为准，vibego 不在本地数据库中复制状态。
ClaudeCode
| 变量 | 说明 |
|---|---|
CLAUDE_WORKDIR |
工程目录（默认与 Codex 相同） |
CLAUDE_CMD |
CLI 启动命令，示例 claude --project <path> |
CLAUDE_PROJECT_ROOT |
JSONL 根目录（默认 ~/.claude/projects） |
CLAUDE_SESSION_GLOB |
JSONL 文件匹配（默认 *.jsonl） |
CLAUDE_PROJECT_KEY |
可选：显式指定 ~/.claude/projects/<key> 路径 |
Gemini
Gemini 基于官方 gemini-cli（Homebrew 包名 gemini-cli，命令为 gemini）。
默认会话落盘路径（可复核）：
~/.gemini/tmp/<sha256(工作目录绝对路径字符串)>/chats/session-*.json
| 变量 | 说明 |
|---|---|
GEMINI_WORKDIR |
工程目录（默认与 MODEL_WORKDIR 相同） |
GEMINI_CMD |
CLI 启动命令，默认 gemini --approval-mode yolo --sandbox（高风险，需自行评估） |
GEMINI_SESSION_ROOT |
会话根目录，默认 ~/.gemini/tmp |
GEMINI_SESSION_GLOB |
会话文件匹配，默认 session-*.json |
启动时会自动把仓库根目录的 AGENTS-template.md 同步到 ~/.gemini/GEMINI.md 的
<!-- vibego-agents:start -->...<!-- vibego-agents:end --> 区块，
用于让 Gemini CLI 自动继承 vibego 的强制规约。
Copilot
Copilot 基于 GitHub Copilot CLI，默认命令为 copilot --yolo，正式回推来源为 ~/.copilot/session-state/**/events.jsonl。
Telegram 命令菜单可通过 /plan_mode 切换 Copilot 的 interactive / plan / autopilot 三态；排队发送默认使用 Ctrl+Q，立即发送仍使用 Enter。
| 变量 | 说明 |
|---|---|
COPILOT_WORKDIR |
工程目录（默认与 MODEL_WORKDIR 相同） |
COPILOT_CMD |
CLI 启动命令，默认 copilot --yolo |
COPILOT_SESSION_ROOT |
会话根目录，默认 ~/.copilot/session-state |
COPILOT_SESSION_GLOB |
会话文件匹配，默认 events.jsonl |
COPILOT_QUEUE_SUBMIT_KEY |
排队发送提交键，默认 C-q；若你的终端环境更适配 Ctrl+Enter，可改为 C-Enter |
aiogram Worker 行为
/start：返回chat_id、MODE、ACTIVE_MODEL；日志打印chat_id与user_id。/session_live：查看主会话与活动并行会话实况。/plan_mode：切换当前终端的 PLAN/MODE 状态。/goal [objective|pause|resume|clear]：仅 Codex worker 可用；裸/goal打开管理面板，带参数时用于查看、设置、暂停、恢复或清除当前 Codex active thread 的目标。- 文本消息：
- 依据
ACTIVE_MODEL解析会话文件：Codex / ClaudeCode / Copilot 为 JSONL，Gemini 为session-*.json； 默认读取current_session.txt中记录的会话路径，必要时搜索MODEL_SESSION_ROOT以回填。 - 将 prompt 注入 tmux（发送
Esc清空模式、C-j换行、Enter提交）。 - 首次读取
SESSION_OFFSETS初始化偏移；随后通过_deliver_pending_messages()补发当前尾部内容并持续轮询 JSONL。 - watcher 阶段提示
ACTIVE_MODEL正在处理中，完成后自动推送结果（保留 Markdown）。
- 依据
- MODE=A 下仍支持
AGENT_CMD直接执行 CLI。
新增脚本
run_bot.sh--model <name>：codex / claudecode / gemini。--project <slug>：日志/会话目录名称；未提供时依据工作目录推导。--foreground：前台运行（默认后台 +nohup）。--no-stop：启动前跳过 stop（默认先执行stop_bot.sh保证幂等）。
stop_bot.sh- 幂等终止：
tmux kill-session、关闭bot.pid指向的进程、移除缓存。 - 示例：
./scripts/stop_bot.sh --model codex --project mall-backend。
- 幂等终止：
配置要点
.env（Master 全局配置）
-
文件位置：
~/.config/vibego/.env（可通过环境变量VIBEGO_CONFIG_DIR自定义）。 -
MASTER_BOT_TOKEN：master bot 的 Token，由vibego init引导输入，启动时必须存在。 -
MASTER_CHAT_ID/MASTER_USER_ID：首次在 Telegram 与 master 交互时自动写入，表示已授权的管理员账号。 -
MASTER_WHITELIST：逗号分隔的 chat_id 列表，留空表示不限制；若与自动写入冲突以最新值为准。 -
其他可选变量（代理、日志级别、默认模型等）可按需新增，未设置时脚本使用默认值。
-
项目配置持久化在
~/.config/vibego/config/master.db（SQLite），对应的 JSON 镜像为~/.config/vibego/config/projects.json。如需离线编辑，可参考仓库内的config/projects.json.example模板。 -
Master「⚙️ 项目管理」可新增/编辑/删除项目；仍可离线编辑 JSON，启动时会自动导入并同步至数据库。
-
必填字段：
bot_name、bot_token、project_slug、default_model。 -
展示字段：
name为项目显示名，可使用短名称；未配置时回退展示bot_name。 -
可选字段：
workdir（项目路径）、allowed_chat_id（用于预设授权）。留空时，worker 首次收到消息会自动记录 chat_id 并写回~/.config/vibego/state/master_state.json。 -
其他自定义字段暂不读取。
微信开发命令端口配置（wx-dev-preview / wx-auto-preview / wx-dev-upload）
wx-dev-preview、wx-auto-preview与wx-dev-upload都会调用微信开发者工具 CLI 的--port，该端口为 IDE HTTP 服务端口；若端口未配置则命令会直接报错。wx-auto-preview调用微信开发者工具auto-preview，用于触发已登录手机自动预览；不生成二维码、不回传图片。- 配置文件：
~/.config/vibego/config/wx_devtools_ports.json（若设置了VIBEGO_CONFIG_DIR/MASTER_CONFIG_ROOT，则路径随之变化） - 配置模板：
config/wx_devtools_ports.json.example - 端口获取：微信开发者工具 → 设置 → 安全设置 → 服务端口（官方文档：https://developers.weixin.qq.com/miniprogram/dev/devtools/cli.html）
自动授权 & 状态
- worker 启动时若
allowed_chat_id为空，首次合法消息会写入state/state.json并立即生效。 - master 重启：先调用
stop_bot.sh清理，再依据 state 还原正在运行的项目。
后续规划
- Master bot 将统一轮询多个项目 bot，并调用 run/stop 脚本管理 worker；当前版本先提供 worker 端结构与日志规范。
- Gemini / Copilot 已接入；后续可按需补充更细粒度的工具调用回推与会话管理能力。
注意
~/.config/vibego/.env内包含敏感 Token 与管理员信息，请勿提交至版本库。- 若需减少日志体积，可按需清理
logs/<model>/<project>/或调整脚本输出阈值。 - 如果以源码仓库方式运行过旧版本，请执行
./scripts/migrate_runtime.sh并确认仓库中仅保留.example模板文件，避免误将数据库或日志提交至 Git。 - Master 会缓存版本检测结果，每个版本只提醒一次；如需立即重试可执行
/projects或重启 master。
Master 控制
- 管理员 Bot 使用
MASTER_BOT_TOKEN启动（运行python master.py）。 - 项目列表由 Master 仓库（
~/.config/vibego/config/master.db）维护，可通过项目管理按钮或~/.config/vibego/config/projects.json同步文件更新。示例字段：name：项目显示名（展示用，可短名；不影响日志目录或 Telegram bot 用户名）bot_name：对应 Telegram 机器人的用户名（可带或不带@，展示与交互时自动加@）bot_token：对应 worker 的 Telegram Tokendefault_model：默认模型（codex / claudecode / gemini / copilot）project_slug：日志/目录名称workdir：项目工作目录（可选）allowed_chat_id：项目 worker 的授权 chat（用于 run_bot 时注入环境）
- 状态持久化：
~/.config/vibego/state/master_state.json自动记录各项目当前模型与运行状态，master 重启时会先stop_bot.sh清理现场，再根据状态恢复。
管理命令
| 命令 | 说明 |
|---|---|
/projects |
列出所有项目当前状态与模型 |
/run <project> [model] |
启动指定项目 worker，模型可选（默认使用当前/配置值） |
/stop <project> |
停止项目 worker |
/switch <project> <model> |
停止后以新模型重新启动 |
/start |
显示帮助与项目数量 |
/upgrade |
执行 pipx upgrade vibego && vibego stop && vibego start 完成自升级 |
<project>参数可填写project_slug或对应@bot_name，命令回复将自动展示可点击的@链接。
master 仅与管理员 bot 交互；项目 bot 仍由 worker（run_bot.sh 启动的
bot.py）负责处理业务消息。
1 maintainer
Metadata
1 maintainer
Release files for vibego 1.5.216
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vibego-1.5.216.tar.gz | 1.8 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vibego-1.5.216-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.7 MB
Release files / vibego-1.5.216.tar.gz
| Download URL | vibego-1.5.216.tar.gz |
|---|---|
| Size | 1.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9ac2b0bcd98533040865fbfbf7947be9046cbc8acda1addd5f61b2c9f3c7b6b9
|
|
BLAKE2b-256 checksum How to use checksums |
4aec01e39520f298b4e0bcb0aeb8ba180e7e961875abdc528d2d618d05267710
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.15
|
Release files / vibego-1.5.216-py3-none-any.whl
| Download URL | vibego-1.5.216-py3-none-any.whl |
|---|---|
| Size | 1.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6da254c66245dceafbf26cace8131a4b71214c9cc36118d34ad9574568ea2034
|
|
BLAKE2b-256 checksum How to use checksums |
cf1c2a6224ee391747c7732eb2484c59960a90d0d7bafa3aa93e10f4eef1dc5c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.15
|
