convez.ai
MCP Server
SuperMarioYL

agentq

SuperMarioYL/agentq

Ver no GitHub
InicialPluginScore · de 0 a 100

N agents, 1 human: an approval triage queue for coding agents — wrap, serve, attach, approve from your phone.

Instalação

$npx convez-ai SuperMarioYL/agentq

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
v0.18.0
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

agentq

English | 简体中文

agentq 把 N 个并行 Claude Code 会话的审批请求收敛到同一个手机队列。

目录

为什么需要它

你在 tmux 里同时开了 4 个 Claude Code 会话,每个都会停下来问"允许这条 bash 吗?""可以改这个文件吗?"——但你不知道当前哪一个在等你。alt-tab 一圈才找到要回答的那个,写代码的时间被切碎成了"找窗口 → 点 Yes → 找下一个窗口"的循环。社区里这叫 George Jetson 时刻——见 r/LocalLLaMA 上的原帖,以及 affaan-m/everything-claude-code 里围绕多 Claude Code 会话整理的工作流。

agentq 把这件事翻转过来:审批不再绑死在终端窗口里,而是聚拢成手机上的一个有序队列。哪个 Agent 在等你,扫一眼就知道;按一下就放它过去。

10 秒上手

# 安装(任选其一)
brew install SuperMarioYL/tap/agentq          # macOS
go install github.com/SuperMarioYL/agentq@latest

# 终端 A:起守护进程,记下打印的 token
agentq serve

# 每个 Agent 终端:用 wrap 套住 Agent
agentq wrap -- claude

# 桌面终端:打印手机扫码
agentq attach --token <粘 token>

扫码、点 Approve、Agent 解锁——首次审批一般在两分钟以内完成。

演示

📼 演示动图正在录制中(见 assets/demo.tape 的脚本)。落地后会出现在这里:![demo](assets/demo.gif)。

架构

  [claude #1] ─┐
  [claude #2] ─┤   stdio 拦截    ┌──────────────┐    WebSocket    ┌─────────┐
  [claude #3] ─┼──> agentq wrap  ──>│ agentq serve │ <───────────>  │ 手机 UI │
  [claude #4] ─┘    (每会话)     │  bbolt 存储  │                 │ (扫码)  │
                                    └──────────────┘

三个进程都跑在你自己的机器上:

  • agentq wrap:很薄的 pty + stdio 嗅探器,识别 Agent 的审批提示,按 ApprovalEnvelope JSON 上报;
  • agentq serve:单文件 Go 二进制,绑定 127.0.0.1:7777,提供 HTTP + WebSocket + 内嵌 SPA;
  • agentq attach:算出本机 LAN IP,把 http://<ip>:7777/?t=<token> 编成终端二维码。

没有 Docker、没有 SaaS、没有外部数据库。

HTTP / WebSocket API

路由方法作用
/api/envelopesPOST发送 ApprovalEnvelope,长连接阻塞直到拿到答复(或 TTL 到期)
/api/queueGET列出当前未答复的 envelope,按 ULID 升序
/api/queue/:id/answerPOST提交 { "choice_key": "y" }
/wsWebSocket推送 {kind:"envelope"} / {kind:"answer"} 事件,初次连接会推送当前快照
/healthzGET无需 token 的存活检查

所有 /api 和 /ws 都要求 ?t=<token> 或 Authorization: Bearer <token>。

ApprovalEnvelope 的字段在 internal/protocol/approval.go 里定义;公开它是 agentq 的护城河——任何 Agent 运行时都能直接发同样的信封,绕过 stdio 拦截。

配置

字段类型默认值含义
--listenhost:port127.0.0.1:7777守护进程监听地址
--lanboolfalse把 --listen 改成 0.0.0.0:<port>,让手机能进来
--data-dirpath$XDG_DATA_HOME/agentq 或 ~/.agentqbbolt 文件所在目录
--tokenstring自动生成客户端必须带的 bearer token
--token-outpath不写把 token 写到文件,attach 可用 --token-file 读

agentq wrap 沿用 m1 已实现的 stdout/stdin 协议,可以通过外部桥脚本把每行 envelope POST 给守护进程;与 wrap 内置 daemon 模式的集成会在 v0.1.1 合入。

对比 affaan-m/everything-claude-code

affaan-m/everything-claude-code 是一份围绕 Claude Code 工作流的精选清单,定位是"资源整理";agentq 解决的是清单里至今缺席的多会话审批收敛问题。两者并不冲突——把 agentq 放到清单里反而是好事。

维度agentqeverything-claude-code
多会话审批收敛 N→1✓—
ApprovalEnvelope 开放协议✓—
工作流资源精选—✓
单二进制工具✓—
适用于多 Agent 并行✓partial

路线图

  • m1:wrap 单 Agent,stdout/stdin 驱动
  • m2:N 个 wrap → 一个 daemon,bbolt 持久化,REST + WS
  • m3:手机端响应式 SPA + 终端二维码
  • v0.2:Windows 支持;Cursor / Codex 适配器(社区 PR 友好)
  • v0.3:Team 模式(共享队列 + 审计日志),按需付费

协议与贡献

MIT。问题、想法、协议讨论一律走 Issues;想加新 Agent 适配器就直接发 PR,ApprovalEnvelope 一旦公开就是大家的协议。

推送仓库后建议加 topic:

gh repo edit --add-topic claude-code --add-topic agent --add-topic mcp

Share this

agentq —— 把 N 个并行 Claude Code 会话的审批塞进一个手机队列。开源、单二进制、30 秒上手。Agent 多了 alt-tab 找不到哪个在等你?扫码就行。 https://github.com/SuperMarioYL/agentq
Ver o original no GitHub

Relacionados