agent-autoloop README

The project's README from github.com/KKKKhazix/agent-autoloop. As one markdown file: README.md.

Agent Autoloop

让你的命令行 Agent 在后台自己接活、自己跟进到底；平时不烦你，遇到拿不准的事才发卡片找你拍板。

中文 | English

上手 · 场景模板 · 插件 · 内核 · 文档

架构图

它解决什么问题？

平时我们用 Claude Code、Codex 这类命令行 Agent，大多是“人守着终端用”：你输一句话，盯着它跑，等它问你下一步；一旦关掉窗口或者人走开，事情就断了。

Agent Autoloop 是一个极轻量的自动化中台。它把任务调度做成一个零外部依赖的内核，把事件来源、Agent、通知通道，甚至代码上线流水线全部拆成可随时插拔的插件。

上手

支持 macOS 和 Linux。运行前需要装好 Node 24、Git、curl，以及任意一个你已经登录好的命令行 Agent，不需要 GitHub 账号。也可以直接把安装说明丢给你的 Agent，让它替你装好。

Windows 版：待定。 很多朋友在问 Windows 版，我都看到了。我现在人在外面出差，手边没有 Windows 电脑，没法真机开发和测试，所以现在还不能在 Windows 上用。这个周末（11 月 7、8 日）回家后，我会把它开发完，做完兼容性测试，再正式推出。进度会更新在 #17。

curl -fsSL https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.sh | sh

安装和 agent-autoloop update 都装最新的 Release，那是通过了全部检查的版本。

装好后用你本机的 Agent 真实走一遍“提问 → 退出等回复 → 拍板 → 接着干完”：

agent-autoloop try

下面是在终端里的真实输出：

事件发出去了，Agent 开始干活……

Agent 结束了这一轮，问了你一个问题。它现在不占进程、不花 Token。

【等你决定】#1 试跑：选一个颜色
这是一次试跑，选哪个都行。
  1. 蓝色
  2. 绿色
回答：agent-autoloop answer 1 <序号>
答完运行 agent-autoloop status，能看到它接着把活干完。

交互终端里直接输入数字回车；非交互终端运行 agent-autoloop answer 1 2 选择“绿色”。再跑 agent-autoloop status，就能看到它接上刚才的会话并显示“你选了绿色，试跑通过”，还有今天和最近 7 天的轮数、Token 和费用（统计口径）。

一件事怎么转起来

编号和上面的架构图一一对应：

  1. 新事件进来。 早上 9 点的定时任务、GitHub 上新提的 Issue、业务系统报的错，都变成一条标准事件送进内核。
  2. 按规则派活。 内核照你写的规则，决定交给哪个 Agent、去哪个目录干。同一件事排队时又来的消息，会合并成一轮处理。
  3. 干完一轮就退出。 Agent 把结果写在最后一条回复里，进程直接退出。
  4. 拿不准才问你。 碰到删数据、重启服务、花钱、对外发消息这类事，内核通过飞书或桌面通知发一张卡片给你。等你回复期间，它不占后台进程，也不消耗 Token。
  5. 点一下，接着干。 你选完，它接上原来的对话，把剩下的活干完。

能自己搞定的事走图上方的自动闭环：直接办完，或者约个时间（比如半小时后）再醒来复查，全程不打扰你。

日常怎么配？

写一份规则（rules.json）

不需要写胶水代码。打开 ~/.agent-autoloop/rules.json，在 rules 里写清楚什么事、交给谁、在哪个目录干。to 填 agents 里已有的名字。比如每天早上 9 点写早报：

{
  "name": "早报",
  "when": { "cron": "0 9 * * *" },
  "to": "codex",
  "cwd": "~/notes",
  "prompt": "整理昨天的笔记和提交，写今天的早报。"
}

外部事件写法一样，只是要先接好来源。比如有人提新 Issue 时交给 Codex，先按说明在 sources 里登记 github：

{
  "name": "处理 issue",
  "when": { "source": "github", "types": ["issues.opened"] },
  "to": "codex",
  "cwd": "~/code/app",
  "skill": "handle-issue",
  "parallel": 3
}

保存后几秒内自动生效，可以运行 agent-autoloop check 检查。就算改错了，或者文件被删、读不到，系统也会继续按旧规则跑，并发卡片提醒你。

Agent 怎么跟中台配合？

中台对 Agent 只有一个约定：在最后一条回复里交代结果。事情办完了，正常输出一句结论就行。需要向你请示时，在回复末尾附一段 agent-autoloop 代码块：

订单已经核对完毕，库存充足。

```agent-autoloop
{
  "ask": [{
    "title": "怎么发货？",
    "text": "两种方式今天都能发出。",
    "options": ["快递", "自提"],
    "key": "shipping"
  }]
}
```

除了提问（ask），还能发通知（notice）、关闭已解决的卡片（resolve）、预约复查（later）和触发新事件（events）。通告不需要回答，但结案时可以顺手写一句处理说明，这句话会留在卡片上。万一 JSON 写错了，中台只让它在原会话里重写最后这段回复，不会把已经干完的业务重做一遍；重写也失败时，保留原结论并通知你回执没有生效。接着旧会话跑也一样：会话接不上才开新的；接上了、干到一半断了，就算没跑成，过几分钟回到原会话重试，不开新会话重做。

拿来即用的场景模板

每套模板都带规则、任务 Skill 和启用说明。

想做什么 已经封装好的流程
每日早报 默认每天 8 点整理本地笔记和 Git 提交，写入 briefs/YYYY-MM-DD.md
跟进 GitHub Issue 每 5 分钟查新 Issue，在本地改代码并通知你查看；不提交、不推送、不回复 Issue
线上告警排查 接收报错、对照代码查原因，需要重启时发卡片询问，回答后继续
用户反馈处理 重读反馈当前状态、修复、交付核实、准备回复；需要决定时飞书问你，回答后继续
网站巡检 每 5 分钟检查状态和关键内容，首次异常交给 Agent，持续异常不重复通知，恢复后更新原卡片
飞书周报与业务摘要 周日 18 点按你的权限读汇报和指定表格，生成本地摘要；飞书只发简短摘要，完整稿留在本机
PR 自动交付 打上 deliver 标签后，审查、等 CI、合并、等发布并核对线上版本

启用： 打开对应说明，把任务 Skill 放进所用 Agent 的 skills 目录，把示例规则合入 ~/.agent-autoloop/rules.json，替换电脑名和路径，再运行 agent-autoloop check。

反馈处理、网站巡检和飞书摘要默认使用北京时间，只发给本人的飞书私聊。样例数据都是虚构的；脚本和回执只用本地 HTTP 与假飞书 CLI 验证过，没有在真实账号上跑过完整业务。

更多模板：Claude 委托 Codex 处理网页、每周代码清理、交付 PR。

插件体系：四个方向都能自由替换

内置插件随程序安装，填好配置即可启用；第三方插件用 agent-autoloop add <git 地址> 安装。

方向 内置 配置
事件：怎么发现新活 GitHub Webhook、GitLab Webhook、HTTP 接口、定时规则、Issue 轮询脚本 说明
Agent：谁来干活 Claude Code、Codex、ACP、通用命令 说明
通道：去哪找你拍板 桌面通知（默认开启）、飞书、钉钉 / 企微 / Slack / Discord 说明
交付：把 CI/CD 也做成插件 delivery 说明

实测情况： Claude Code、Codex 和 ACP（官方 Codex ACP 适配器）跑通了多轮问答和跨进程会话续接；飞书跑通了发送、按钮回调和卡片更新；四种 Webhook 模板只在本地模拟服务上验证过，GitLab Webhook 按官方文档的格式测试，没连过真实 GitLab。这些文字通道靠回答链接拍板，要把 hub.publicUrl 配成手机或电脑能打开的地址。

其他命令行 Agent 一行接入。 设置 use: "command" 并传入命令数组，{prompt} 作为独立参数传递，不会被当成 shell 代码执行。下面的命令整理自各家官方文档，我们还没有逐个跑过：

Agent 接入命令
DeepSeek Harness dsh --profile headless {prompt}
pi pi --print {prompt}
OpenClaw openclaw agent exec {prompt}
Hermes hermes chat -q {prompt}
Cursor agent -p --trust {prompt}
WorkBuddy / CodeBuddy codebuddy -p {prompt}

交付流水线。 给 GitHub PR 打上 deliver 标签后，它会自己跟进到上线：审代码 → 等 CI → 合并 PR → 等部署 → 核对线上版本。审查和交付配置只从 main 读取，绝不在接单电脑上检出或运行 PR 里的代码；排队、并发和重试直接复用内核。

写自己的插件。 从 Agent、通道、事件 三个可运行的最小模板开始，见插件开发说明。要让 Agent 操作网页，先看浏览器接入。命令行和 MCP 也能查看和回答卡片。

内核的四个机制

内核约 1800 行代码、零运行时依赖。它不读系统时钟、不用随机数、不向外发请求，插件主动连进来，账号凭据留在各自的插件里；同样的输入永远得出同样的结果。它把四个计算机领域的成熟做法用到了命令行 Agent 上：

自己跑一遍

在程序目录 ~/.agent-autoloop/app 下运行：

验证什么 命令
任何一轮的来龙去脉 agent-autoloop why 1
20 万步模拟断网、丢包、崩溃和重复提交，一个种子就能复现 node sim/random.ts 24301 200000
强杀进程 1000 次，已确认的记录一条不丢 node sim/crash.ts 1000 12648430
下面的性能数字 npm run benchmark 
第 1 轮 · 演示
11-03 20:47:25  规则版本 #1
11-03 20:47:25  触发事件：来源 local · 类型 demo.start · 对象 example
11-03 20:47:25  local 领取（演示程序）
11-03 20:47:25  结束：演示完成

实测性能

Apple M5 Pro、24 GB、Node 24.21.0。写入逐条提交，事务落盘后才应答。npm run benchmark 的达标线按这台机器定，换台机器可能报未达标。

指标 实测
冷启动 88.78 ms
空闲内存 59.94 MB RSS
1000 个同时等待的长轮询 170.49 MB RSS
持久化写入 2394 条/秒
派活 p99 1.82 ms
排队 5000 时被挡下的心跳 p99 1.66 ms
110 万条事实时的启动 99.8 ms
内核行数（含空行和注释） 1651
运行时依赖 0

历史变大后，状态汇总会变慢，日志和索引也继续占磁盘；格式变化后的首次启动要从日志全量重建，110 万条用时 43.1 秒。完整数据和测法。

用量与合规说明

中台直接调用你本机已经安装并登录好的命令行工具，不会读取或转存你的账号凭据。模型调用消耗算在你自己的账号名下，额度和使用范围遵循各家模型厂商的服务条款。

在高频自动化场景下，各家厂商通常更建议使用 API Key（个人订阅额度主要是为日常人工交互设计的，详见 Anthropic 与 OpenAI 的官方说明）。如果你用它对外提供服务，请使用 API Key。本项目为独立开源项目，与上述厂商无隶属或背书关系。

更多文档

仓库目录
位置 放什么
kernel/ 内核：决策、事实日志、状态投影、到期任务、规则匹配、接口行为与卡片表单
host/ 运行外壳：Node HTTP、文件与 SQLite 连接、时钟、配置、后台服务和插件加载
protocol/ 通信格式、JSON Schema、输入校验、HTTP 客户端和一致性检查
worker/ 接单程序：领活、运行 Agent、心跳与停止、读取和提交回执
cli/、bin/ 用户命令及启动入口，包括状态、回答、why、MCP、更新与卸载
plugins/ 内置 Agent、事件、通道和交付插件
examples/recipes/ 完整场景：规则、任务 Skill 和启用说明
examples/plugins/、examples/skills/、examples/*.sh 最小插件模板、独立任务手册和 Shell 示例
skills/agent-autoloop/ 中台的正式配置与操作手册，安装时也提供给 Agent 使用
docs/ 通信协议、插件开发说明与中英文架构图
tests/、sim/ 日常行为测试，以及模拟、穷举、强杀和变异检查
scripts/、.github/workflows/ 性能与真机验证、安装冒烟脚本，以及 Linux / macOS CI
根目录文档与 install.sh 中英文 README、安装说明、安全边界、开发约定、许可证与安装脚本

读代码可以从 bin/agent-autoloop.ts → cli/main.ts 开始，再按功能进入 host/、worker/ 或 plugins/；内核设计先看协议。同名文件分属不同层：host/http.ts 转换 Node 请求，kernel/http.ts 定义接口行为；protocol/rules.ts 校验输入，kernel/rules.ts 定义规则类型和匹配。

MIT License

agent-autoloop (KKKKhazix/agent-autoloop)

Searching Database…

2.5K ·GitHub
Agent-autoloop
What is this?Agent Autoloop is a lightweight background hub for command-line agents like Claude Code and Codex. It picks up events on its own, keeps the agent working, and only sends you a card when it needs your decision.
Is it a tool I install or a library I build into my code?It is a self-hosted CLI tool, not a library. It runs on your own Mac or Linux machine with no cloud server and no open ports. There is no web dashboard; cards arrive in chat apps or as desktop notifications.
How do I get it running?Install Node 24, Git and curl, plus any command-line agent you are already logged into. Then run the install script, or hand the install instructions to your agent and let it set things up for you.
Do I need an API key or just a logged-in agent?You do not need a GitHub account, and the hub calls the agent CLI you already use. For heavy automation the README advises an API key, because personal subscription quotas are meant for everyday manual use.
Does it work on Windows?Only macOS and Linux work for now. The author plans a Windows version after compatibility testing, with progress tracked in issue #17.
How does it avoid burning tokens while waiting for my reply?The agent process exits after each round, and the pending decision is stored in the database. Waiting costs no agent process and no tokens, and when you answer, it picks up the same conversation.
Which agents and chat channels are supported?Built-in agents include Claude Code, Codex and ACP. Channels include desktop notifications, Feishu, DingTalk, WeCom, Slack and Discord. Any command-line agent that prints its last reply can be connected with one config line.
Can it take a PR all the way to production?With the delivery plugin, a PR labeled deliver gets reviewed, waits for CI, merges, waits for deployment and checks the live version. Review settings are read only from main, so PR code never runs on the worker machine.
What are similar projects?woml, LangBot, oh-my-subagents, epiq, EvoQuant, Horizon, brigade, cc-connect
Which topics is it in?zero-dependencies, event-sourcing, background-jobs, feishu, webhook, event-driven, scheduler, human-in-the-loop, ci-cd, messaging, notifications, slack
Creator
KKKKhazix
Size
0.6 MB
Stars
2.5K
Updated
CommitNov 05Releasev1.0.0Nov 03
Age
1d
Commits · 90 Days