AG2CLI
GitHub

AG2CLI： Agent to CLI

AG2CLI 与 Codex CLI、Claude Code 同属终端 Agent 工具。你可以描述任务、查看工具活动、处理审批并审阅结果。

AG2CLI 不绑定特定 API 提供商，API Key 由你提供（BYOK）。支持 OpenAI API Compatible 与 Anthropic API Compatible 两种 API 协议。

TUI终端调用，交互式
Headless RUN脚本调用，非交互式
Web / Mobile Remote Control局域网/异地组网，和 ag2cli serve 配对连接
Desktop Electron内嵌 AG2CLI
AG2CLI共享执行内核
LLM APIBYOK · OpenAI API Compatible · Anthropic API Compatible
用 DeepWiki 探索 AG2CLI
交互式 TUI

workspace: /Users/ag2dev/workspace/ag2cli

model: deepseek-flash

type a message, @ to mention, / for commands

ag2cli 是什么？回复简洁，不含代码和文件，wikipedia 风格。

[done] bash · List repo root

[done] read_file

AG2CLI 是一个 agent CLI、Session 运行时，以及可选的多客户端协议服务。它由共享执行内核加上多个入口组成：本地 TUI 与 headless run 在进程内运行，serve 则作为长期后端，通过 App Server Protocol（JSON-RPC/WebSocket）为 Web、手机与未来桌面客户端提供服务。仓库采用 monorepo 分层，划分 core、runtime、protocol、client 与协议契约等 workspace 包，使领域、运行时、Host 组合与客户端边界可独立测试与替换。其 Canonical Session 事件流是持久历史的唯一事实源，客户端仅发送命令并读取投影。

done · 2 turns · 3.4s

openai · deepseek-flash · context 9.4k/128k (7.4%) · completed · ⏸ manual · effort medium · idle

本地优先 BYOK · 自带 API Key 可检查、可继续的任务 远程客户端 · Web 进行中 / Mobile Remote Client 计划中

先看能做什么，再看如何做到。

先从工作方式和任务结果了解价值，再按兴趣深入执行、安全与架构。

本机运行与远程接入

TUI 与 headless run 在本机执行；Web / Mobile 通过 Serve 远程控制。Desktop Electron 内嵌 AG2CLI，作为本地桌面应用运行。

客户端形态、状态与连接路径用户视角

本地入口

在本机或编辑器进程内使用

当前可用

编辑器集成

ACP v1 · stdio adapter

ag2cli acp
当前可用

终端与自动化

交互式 TUI · 脚本 / CI

ag2cli · ag2cli run

远程客户端

两种客户端形态，同一 Serve API；交付状态与连接网络分别说明

进行中

Web Remote Client

桌面与手机浏览器 · 当前客户端

apps/web独立 Web 应用；连接 Serve API
计划中

Mobile Remote Client

Android / IOS

桌面 / 手机浏览器 · Android / IOSWeb 进行中 · Mobile Remote Client 计划中
局域网 / 用户配置的异地组网网络路径由用户配置
ag2cli serve多个客户端可连接同一 Serve 与 Session

Serve 默认只监听本机；局域网需显式配置，异地访问需配置可达网络。非本机连接需要 WSS 与应用认证。AG2CLI 不提供内置中继或自动组网。

Desktop Electron

内嵌 AG2CLI 的本地桌面应用

暂缓

Desktop Electron

内嵌 AG2CLI，作为本地桌面应用运行。

从描述任务，到检查并交付工作。

Agent 可以在授权工作区内读取和修改文件、调用工具并委派子任务；你能看到执行进展，在需要时介入，最后检查结果并继续处理。

01描述任务
02观察执行
03控制工具
04检查产出

在真实工作区里做事

读写项目文件、运行 shell 工具；工具作用于明确的 workspace，并遵循当前会话的权限设置。

看见并介入工具活动

检查 Agent 正在做什么；需要审批时明确批准或拒绝，也可以取消仍在运行的任务。

把子任务并行委派

Agent 可以把边界清楚的工作交给子 Agent；结果和完成通知回到父任务，继续汇总。

检查结果，再继续工作

查看文件变化与工具结果，恢复可继续的 Session；调整对话历史不会自动撤销文件或其他外部副作用。

入口不同，执行语义仍可对齐。

每种入口组合自己的 Host 与连接边界；Agent Runtime、Session invariants 与 provider/tool ports 构成共享的执行基础。

调用边界、Host 与 Agent Runtime 包层内部架构

01 · 入口协议与客户端契约

本地路径 · 进程内TUI / run → SessionClient

私有 Session command / codec；不开放网络 listener

@ag2cli/client · @ag2cli/protocol
编辑器路径 · 标准协议ACP v1 → ag2cli acp

stdio adapter → 独立的临时 Host

远程路径 · 公开 API浏览器 / Mobile → App Server API

JSON-RPC 2.0 · WebSocket / WSS · serve 提供

@ag2cli/app-server-protocol

可选远程 toolkit：@ag2cli/app-server-client；其他客户端也可直接实现公开契约。

Host composition 把 API / 本地接缝连接到对应运行实例 ↓

02 · apps/cli Host composition

TUI Host

本地交互与审批面

Headless Host

本地自动化执行

Serve Host

一个 Serve · 多个客户端可 attach 同一 Session

ACP 临时 Host

一次集成调用 · 不附着到 serve

Anthropic API Compatible / OpenAI API Compatible model adapter
Workspace 与工具 adapter
EventStore 与持久化 adapter

组合层注入 Runtime ports；公开 App Server RPC 经 method facade 路由到 Serve Host。

运行时按用例编排；Session 契约与领域规则由独立 packages 承载 ↓

03 · Agent Runtime 内部分层与依赖 packages

@ag2cli/runtime

应用用例、执行协调与外部能力 ports

application/sessionSession 命令、协调与审批
application/executionAgent Loop、模型轮次与工具生命周期
context / prompt构造模型所需上下文与提示
task后台任务状态与调度
ports模型、工具与持久化接口
@ag2cli/protocol

私有 Session command / codec

@ag2cli/core

Session 领域、canonical events 与 invariants

Package 依赖：runtime → protocol + core；protocol → core；client → protocol + core；app-server-client → app-server-protocol。

上方分层表示请求 / 调用路径虚线框表示由 composition 注入的 adapter

TUI / run 使用私有本地契约；Web 与移动客户端通过公开 App Server API 进入 Serve Host。ACP v1 走 stdio adapter，并使用独立的临时 Host。不同 Host 复用 Runtime packages，但各有独立运行实例与生命周期。

先记录事实，再让界面呈现事实。

一次任务中，Agent 先向你配置的模型请求下一步；需要工具时，系统按会话权限决定执行、询问或拒绝。工具结果确认后再更新本次 Session，界面据此展示进展。下面的时序图展开提交与副作用之间的技术边界。

模型与工具结果都通过 Session authority 提交一次执行
AG2CLI 工具调用时序 用户提交输入，runtime 请求模型并准备工具调用，authority 在每个外部副作用前后协调 canonical event 的提交，客户端根据已提交事件更新。 用户 / TUI提交任务 Runtime执行工作流 Session authority状态与写入权威 模型 Provider用户选择的服务 Tool host工作区与工具 输入 / submit 记录已接受输入与 attempt 允许该代执行 模型请求 / 响应在提交锁之外 校验 typed proposal 与 revision 提交确认后的 model event 准备、判权后再执行工具 工具结果作为 proposal 返回 校验并提交 canonical result

左右滑动查看完整图表

副作用在 commit lock 外运行；worker 回来后仍须通过 generation、attempt 与 revision 校验，不能直接写 Session history。

子任务可以并行，结果会回到主任务。

headless run 不把主 run 返回当作整个进程的终点：它等待子任务 settle，将结果记录到任务状态与父 Session 通知，再启动 continuation run 消费通知。

从 async spawn 到 continuation input跨 run 协调
AG2CLI headless 异步子任务 continuation 时序 Headless 进程启动父 run，父 Runtime 异步 spawn 子 Agent 并立即收到 handle。主 run 返回后进程继续等待；子 Agent settle 时，父 Session authority 记录任务终态和待消费通知。Headless 观察到通知后启动 continuation run，由父 Session 消费该输入。 Headless 进程run 生命周期协调 父 Runtime主 run / continuation Child Agent临时执行上下文 父 Session authority任务终态与 canonical input 启动主 run agent(async: true) → spawn 立即返回 child handle RunCompleted：主 run 的事实已提交 主 run 返回；进程继续 drain task terminal + InputAccepted(notification) drain 完成后，snapshot 确认通知待消费 启动 continuation run InputConsumed → 后续结果继续提交

左右滑动查看完整图表

子任务报告作为 task output 保留；父 Session 中的 notification 是可恢复的输入锚点，不是瞬时 UI 消息。continuation 若再次 spawn 子任务，headless 协调循环会继续处理。

工具执行先过一道明确的判断。

准备阶段描述将要发生的效果；canonical permission judgment 根据 Session policy 给出唯一判定。客户端不自行猜测“这次是否可以放行”。

从准备事实到授权、审批或拒绝安全边界
AG2CLI 工具权限判断流程 工具调用先被准备并由唯一的 canonical 判定产生 allow、ask 或 deny；审批需要交互面，缺少审批面时会安全拒绝。 Prepared tool call目标、参数与 effect facts先检查确定性约束 唯一的 canonicalpermission judgment ALLOW可执行 ASK需要审批 DENY不执行副作用 Tool executor执行同一 preparation 交互式审批用户回答这一次调用批准后才会执行 Fail closed没有审批面时拒绝 不执行副作用 allowaskdeny 有交互面无审批面批准拒绝 决议与工具结果进入同一 Session authority 生命周期

左右滑动查看完整图表

审批回答具体一次、已准备好的调用；策略漂移、资源不匹配或缺少交互面时不静默放行。

已确认的任务事实，可用于恢复和重建视图。

canonical events 保存已确认的 Session 事实。snapshot 可加速恢复；实时 token、在线状态等临时信息负责即时反馈，不代替已确认的任务事实。

Canonical history、snapshot 与客户端 projection数据流
单个 Serve Session 的事实与投影 以一个 Serve Session 为范围：服务端把已确认事件写入 Canonical EventStore；snapshot 和已授权客户端视图从同一份 Session 事实读取或重建；临时流用于即时反馈。 Session authority校验身份、revision 与 transition唯一 durable writer Canonical EventStore已确认事件 · revision · replay唯一事实源 Snapshot重建加速点 · 可由历史重建 远程客户端视图可丢弃的客户端投影 另一个已授权客户端可丢弃的客户端投影 Host 实时流有界内存 · 非 canonical 瞬时事件流 fenced commit 不能取代历史读 / 重建读 / 重建实时投影不进入 replay

左右滑动查看完整图表

rewind 移动 canonical 对话历史的 head，不会回滚文件、Git 或工具已产生的副作用。

授权后远程接入；断线后也能继续观察任务。

serve 让已配对客户端连接同一个远程 Session，查看共同的任务进展与已确认结果；短时交互租约协调谁可以提交。断线或接管不会取消已经开始的 Agent 任务。

首次配对、连接验证与断线恢复HTTP(S) + WS / WSS
AG2CLI 远程 Session 连接与恢复时序 首次配对时，客户端通过 HTTP(S) claim ticket；每次连接先通过 HTTP(S) 获取一次性 challenge，再经 WS/WSS 发送 server.initialize 与设备证明。服务端验证身份和已授权 scope。客户端随后以 session.attach(cursor) 恢复；Serve 建立 observer/replay 屏障，依次返回 snapshot、replay 与实时事件。检测到事件缺口时客户端用 cursor 请求 resync。 Web 客户端保存设备私钥与 cursor App ServerHTTP(S) · WebSocket / WSS Serve Hostdevice / scope / Session authority 首次配对 · HTTP(S) claim ticket 每次连接 · HTTP(S) GET challenge 一次性 challenge + deviceId WS/WSS · server.initialize + device proof 校验身份与 scope · 返回 connection / capabilities session.attach(cursor) 建立 observer / replay barrier snapshot + replay + live events 向客户端有序交付事件 发现缺口 · session.resync(cursor) loopback 可用 WS；非 loopback 连接要求 WSS 与显式配置

左右滑动查看完整图表

pairing link 是短期凭证，不包含 provider secret 或 Session 内容；网络可达本身不代表已获得 Session scope。

可观测性是持续改进的基石。

Session 的 canonical events 是事实源；快照、客户端流、trace、模型调用与遥测都是从事件生成的投影，可以相互核对。

持久事实源Canonical events
Session 快照 客户端事件流 Trace 模型调用 Telemetry

观测深度可控

  • disabled

    关闭模型调用观测记录。

  • metadata · 默认

    保存指纹、Provider / model、用量与状态，不保存完整请求正文。

  • local-full

    完整请求与响应仅持久化在本地，可通过 ag2cli observe 查看。

隐私边界明确

AG2CLI_TELEMETRY · disabled

遥测默认关闭。启用 redacted 后，canonical event 才会投影为脱敏日志；OTel bridge 是可选输出，不是事实源。

  • 密钥字段与常见 token 格式按确定规则脱敏。
  • 脱敏降低敏感信息暴露，不等于匿名化。

项目概况

本项目仍在快速迭代，当前暂为半开源：源码 100% 开源，测试文件与设计决策文档（ADR）闭源；目前不接受外部贡献。

AG2CLI 的目标不是做一个大而全的 CLI，而是构建一组稳定、可组合的产品：LLM API 可自由切换，不绑定任何供应商；支持在局域网内使用私有 LLM API，并支持局域网与多端组网。当前优先稳定各层，下一阶段推进多端开发，因此不会仓促上线。

本项目从零开始开发，并非 fork 后修改。截至 2026-10-15，内部仓库已有约 2,000 次 commit；95% 以上的代码使用 Vibe Coding，代码规模约为 150,000 行（按 tokei 统计）。

AG2CLI 在高比例使用 Vibe Coding 的实践中积累了丰富的经验，并将继续探索如何保持架构清晰、系统稳定，及时识别和治理技术债，支撑项目长期演进。

如有意见、建议或交流，欢迎通过邮件 ag2dev@outlook.com 联系。