jeo-code (jeo)

Encode intention. Decode software.
基于 Bun 的 AI 编码代理 CLI — 需求访谈、经评审的计划、带门禁的执行、诚实的验证。

English · 한국어 · 日本語 · 中文

在仓库内运行 jeo，它会读取文件、编辑代码、执行命令，并把任务推进到完成 — 每一步都通过滚动友好的内联 TUI 实时呈现。

文档

使用指南 — 安装、TUI 操作（↑ 历史、Ctrl+O、! shell）、斜杠命令、/resume、规格优先工作流，附演示视频。

无法内联播放？ 播放/下载演示视频。

亮点

• 多提供商、单一循环 — Anthropic / OpenAI(+Codex) / Gemini / Antigravity / Ollama 统一在一个 JSON 工具循环中。输入框内直接 OAuth 登录(/provider login)，模型选择即刻持久化为默认值。
• 编辑完整性 — read 输出携带内容锚点(42ab|)；带锚点的编辑会与当前文件校验、行移动时自动重映射、不匹配时连同最新内容一起拒绝 — 绝不污染文件。
• 自我修正的验证循环 — 配置 post-edit 钩子(tsc / eslint / 测试)，代理会亲自读取诊断并在循环内修复；钩子未通过时 done 会被阻断。
• 没有表演的真实门禁 — ralplan 共识由真正读取仓库的 critic 子代理执行，[OKAY] 裁决被持久化且 jeo approve 强制要求它；ultragoal 诚实报告(套件运行只是全局信号，绝不伪造逐条通过)。
• 崩溃耐久、本地优先 — 全部状态位于 .jeo/，原子写入、跨进程运行锁、失败任务标记 + 恢复时的部分编辑警告。
• 动态步数预算 — 只要近期工具调用展现新的进展就持续延长，停滞时优雅收敛为总结；子代理保持精确的步数契约。
• 内联 TUI — 已完成的工作流入真实滚动缓冲区(回合中也可用 tmux 滚轮)，代理运行时普通查询输入框仍保持可见并可编辑。Ctrl+O 详细信息切换、主题、剪贴板图片粘贴(Ctrl+V)、CJK/表情安全的宽度计算。

安装

需要 Bun 1.3.14+。

bun install -g jeo-code
jeo --version

快速开始

jeo                      # 在当前仓库启动交互式代理
jeo "整理 README 并跑测试"   # 单次请求
jeo doctor               # 配置 + 模型连通性实测
jeo setup                # API 密钥 / OAuth / 本地模型配置
jeo --tmux               # 在独立 tmux 会话中运行

斜杠命令

在 jeo REPL 中使用(Tab 补全，输入 / 打开面板)。

命令	说明
/model · /provider	选择模型/提供商；/model 在一个流程内显示默认/角色徽章、Ralph 风格嵌套角色·thinking 选择与 OpenAI Codex 角色预设
/provider login <name> · /logout	在输入框内 OAuth 登录/登出
/agents [role] · /subagent	按角色(executor/planner/architect/critic)配置模型·thinking·步数
/thinking [level]	查看/设置默认推理预算(minimal…xhigh)
`/fast [on	off
/skill · __INLINE_CODE_23__lt;skill> [intent]	列出/运行工作流技能($team "任务" 风格)
/view · /diff · /find · /search	代码查看、git diff、文件/模式搜索
/new · /resume · /sessions	会话管理
`/history [n	all]·/export`
/retry · /btw <问题>	重试上次请求 · 不写入历史的旁路提问
/usage · /context · /compact	Token 用量、上下文明细、手动压缩
/theme · /config · /help	主题、运行时配置、帮助
jeo autopilot status	显示分数方向、keep/revert 次数和下一步动作的 ratchet 状态字段

Spec-first 工作流

需求 → 计划 → 批准 → 执行 → 验证，经由 .jeo/state/ 串联，每次交接都有可阻断的真实门禁:

jeo deep-interview "描述你想构建的东西"
jeo ralplan
jeo approve <计划路径>
jeo team
jeo ultragoal

  ┌──────────────────────┐
  │   deep-interview     │  Socratic ambiguity gate · seed frozen when concrete
  └──────────┬───────────┘
             │ .jeo/state/<seed>.json
             ▼
  ┌──────────────────────┐
  │       ralplan        │  Draft + repo-grounded critic → [OKAY] persisted
  └──────────┬───────────┘
             │ requires [OKAY] verdict
             ▼
  ┌──────────────────────┐
  │       approve        │  Schema + roles + [OKAY] — unlocks execution
  └──────────┬───────────┘
             │
             ▼
  ┌──────────────────────┐
  │        team          │  Serial executor · run lock · mutation audit
  └──────────┬───────────┘
             │ all tasks done
             ▼
  ┌──────────────────────┐
  │      ultragoal       │  Honest verification — suite once, no fabrication
  └──────────────────────┘

• deep-interview — 基于歧义度评分的苏格拉底循环；只有标准足够具体才冻结种子(纯含糊标准会被拒绝)，且种子必须通过自身解析器的往返校验。新想法绝不会静默复用已完成的访谈。
• ralplan — 起草阶段 + 真正读取仓库的 critic 子代理门禁: 强制并持久化 [OKAY]/[ITERATE]/[REJECT] 裁决。无效计划(schema、未知角色)不会被标记为 complete。
• approve — 校验 team 执行的确切契约(schema+角色)，并要求持久化的 [OKAY] 共识裁决。
• team — 串行计划执行器: 跨进程运行锁、过期计划重置、按任务的子代理契约、父侧变更审计(零写入的"完成"会被标记)、失败标记 + 恢复时的部分编辑警告。
• ultragoal — 诚实验证: 套件作为全局信号只运行一次，标准只被记录，绝不伪造为逐条通过。

验证钩子(自我修正)

先全局启用一次(在 ~/.jeo/config.json 中设置 "hooks": { "enabled": true })，再为项目添加 post-edit 检查，代理会读取失败并在 done 之前修复:

// .jeo/hooks.json
{
  "enabled": true,
  "hooks": [
    { "event": "post-turn", "match": { "tool": "edit|write" }, "run": "bun x tsc --noEmit" }
  ]
}

非零退出钩子的输出会附加到模型读取的工具结果中(批内去重)；钩子未通过就调用 done 会收到带钩子名称的回推。

内存流程

jeo 在 .jeo/memory/ 下保存 本地优先、蒸馏后的项目内存(无远程后端,零原生依赖)。过往会话被蒸馏为 OKF 概念包,下一次会话仅把相关的、受预算约束的切片重新注入系统提示 —— 作为 DATA 而非指令加固。用 JEO_NO_MEMORY=1 完全禁用。

迁移(jeo memory-migrate,一次性 · 幂等). 把旧版单文档 MEMORY.md 无损转换为概念包: ## 标题 → 类型,每个项目符号 → 一个类型化概念,缩进行 → 正文; 重建 index.md/log.md,并把原文件重命名为 MEMORY.md.bak。一旦概念包中已有概念,再次运行即为 no-op。回滚: JEO_MEMORY_LEGACY=1 忽略概念包,通过相同的注入加固读取 MEMORY.md/.bak(JEO_NO_MEMORY=1 仍优先于一切)。

与您现有的代理或机器人协同工作 (Works beside your existing agent or bot)

工具或机器人	推荐的 jeo 命令	边界
Codex CLI	jeo --tmux --worktree <name> 或 jeo	--worktree 指定一个由 jeo 管理的同级 git worktree（basename → 新分支）；对于已有路径，请先 cd 进入。
Claude Code	jeo --tmux 或 jeo --tmux --worktree <name>	jeo 不会成为 Claude Code 的扩展。
OpenCode	jeo 或 jeo --tmux	仅限外部运行器工作流。
Claw Code	jeo --tmux --worktree <name>	jeo 不会安装到或替换 Claw Code。
外部控制器 / 机器人	jeo mcp serve (MCP stdio 服务器)	外部控制器通过 MCP 工具契约驱动 jeo，而非抓取滚动回显。

--worktree <name> 在隔离的同级 git worktree 中运行 jeo（路径存在则复用，否则以 basename 分支创建），因此有风险或需审查的工作绝不会触及您的主检出。jeo mcp serve 通过 stdio 向任何支持 MCP 的控制器公开 jeo 的工具（用 jeo mcp tools 列出）。添加 -q/--quiet（或 JEO_QUIET=1）可抑制启动横幅、欢迎动画、发布说明和恢复提示，使 jeo 能够与其他代理并行运行或由机器人驱动。-p/--print 隐含 quiet。

本地模型

ollama pull qwen2.5:0.5b
export JEO_DEFAULT_MODEL=ollama/qwen2.5:0.5b
jeo doctor && jeo

配置

• 全局配置: ~/.jeo/config.json(模型选择 MRU 持久化)
• 项目状态/会话: <project>/.jeo/

ANTHROPIC_API_KEY=... OPENAI_API_KEY=... GEMINI_API_KEY=...
JEO_DEFAULT_MODEL=...           # 例: ollama/qwen2.5:0.5b
OLLAMA_HOST=http://localhost:11434
JEO_TUI_THEME=cosmic            # cosmic/matrix/solar/red-claw/blue-crab/mono/aurora/synthwave/sakura
JEO_TUI_ALT_SCREEN=1            # 旧版 alt-screen 回合(默认: 内联滚动缓冲)
JEO_STEP_BASE=24                # 动态步数预算的滚动基数
JEO_STEP_HARD_CAP=600           # 绝对终止保证
JEO_STREAM_MAX_MS=300000        # 可选的整体流截止(默认关闭; 约束慢滴流)
JEO_TOOL_OUTPUT_MAX=4000        # 模型可见的工具输出上限(全文溢出到 artifacts)

重试行为通过 ~/.jeo/config.json 的 retry 调整(requestMaxRetries、streamMaxRetries、rateLimitRetries、failFastStatuses 等)。步数预算默认动态 — 只要看到新的进展就延长，停滞时收敛为总结；--max-steps N 恢复有界流程。

发布 (Publishing)

CI 通过 .github/workflows/npm-publish.yml 发布 — GitHub 发布 release 时自动触发，或手动 workflow_dispatch(可选 dry-run)。工作流执行类型检查、测试、令牌校验(npm whoami)后运行 npm publish --provenance。

所需 npm 令牌权限(仓库 secret NPM_TOKEN):

• 对 jeo-code 包具有 Read/Write 权限的 Granular Access Token，或经典 Automation 令牌
• 必须允许"发布时 bypass 2FA" — Automation 令牌始终绕过，granular 令牌需启用该选项

致谢 (Acknowledgements)

非常感谢 gajae-code 带来的灵感。

更新日志 (Changelog)

• [0.7.20] (2026-06-26) — OKF concept-memory retrieval gains a hybrid reranker ported from memsearch. Injection priority no longer rides one raw keyword score — it fuses two complementary ranked channels by Reciprocal Rank Fusion (RRF): IDF-weighted lexical relevance (the sparse/BM25 channel, so rare discriminating terms steer recall) and concept-graph proximity (the local dense/semantic-neighbour channel, so a hub linked from multiple query hits surfaces even with no keyword of its own). All embedding-free and deterministic, layered atop the existing failure-first tier and pinned-invariant reserved budget.
• [0.7.19] (2026-06-26) — The live model picker gains gajae-code's /model provider tabs, and skill invocation is consolidated onto a single $ entrypoint. The picker now shows an ALL tab plus one tab per provider that tab/shift+tab cycles, and skills (including their declared aliases) are invoked only via $ — the slash palette stays builtins-only.
• [0.7.18] (2026-06-26) — Slash-command discovery and the /model flow reach gajae-code parity. The slash palette/autocomplete now fuzzy-matches command names (with a description fallback for intent-style queries), resolved skills can contribute their own /aliases as real dispatchable commands, and /model runs gjc's two-menu target → reasoning flow so a picked model can be assigned to the default or any subagent role with its own thinking budget.
• [0.7.17] (2026-06-25) — Developer workflow parity (gjc dev:link/dev:doctor, adapted for jeo's zero-native-dep Bun runtime): the global jeo command can be linked to run this checkout's source hot to every edit, with a drift doctor that flags when jeo resolves to a compiled binary or an installed copy instead. README gains "Skill migration and bundled skill inspection" + "Development" sections. Also ships OKF concept-memory search/scoring with budget-aware injection and a round of workflow-prompt hardening (anti-punt, todo-first planning, verdict discipline) that keeps every loop escape hatch intact.
• [0.7.16] (2026-06-25) — Bundled skills get a safe installer: jeo skills sync materializes the built-in workflow skills into ~/.jeo/skills, preserving local edits by default, with a CI-friendly --check drift report and a --force overwrite.

See CHANGELOG.md for the full history.