Agent Autoloop hands-on: your coding agents keep working in the background

Agent Autoloop turns Claude Code, Codex, and other command-line agents into a background loop: it dispatches work on a schedule or a webhook, exits while it waits for your call, and resumes the same conversation when you answer. This guide installs v1.6.3, runs the guided trial, and wires a morning-brief rule.

• Who: Agent Autoloop (KKKKhazix/agent-autoloop) — a background automation hub for command-line AI agents, MIT licensed, written in TypeScript.
• What: A kernel of about 1,850 lines with zero runtime dependencies that dispatches schedules and events to CLI agents and asks you only through a notification card when a decision is needed.
• When: Created November 3, 2026; version 1.6.3 released November 7, 2026; 3,938 stars and 715 forks as of November 7, 2026.
• Requirement: Node.js 24 or newer, Git, and a signed-in command-line agent; macOS and Linux also need curl. No GitHub account, no cloud server, no inbound ports.
• Performance: Cold start 88.78 ms, 59.94 MB idle memory, 2,394 persistent writes per second, dispatch p99 1.82 ms — measured on an Apple M5 Pro with 24 GB RAM and Node 24.21.0.
• Cost: While waiting for your answer, no agent process runs and no tokens are spent; model calls bill to your own account.

Claude Code and Codex are great until you have to babysit them. You type a prompt, watch it run, answer its questions — and the moment you close the terminal or walk away, the work stops. Agent Autoloop closes that exact gap: it is a small background hub that hands scheduled work and incoming events to your command-line agents, then gets out of the way until a decision is actually yours to make.

The project is KKKKhazix/agent-autoloop, MIT licensed, and it is moving fast: 3,938 stars and 715 forks on GitHub, created November 3, 2026, with version 1.6.3 released today, November 7. The idea is having a moment — DeepSeek's own proactive coding agent takes the same approach from the model side. This guide installs 1.6.3, runs the built-in trial end to end, and wires a real morning-brief rule — then shows how it hands new GitHub issues to an agent and asks you before anything risky happens.

What you'll need#

• A machine running Windows, macOS, or Linux. Everything runs on your own computer — no cloud server, no inbound ports.
• Node.js 24 or newer, and Git. macOS and Linux also need curl. No GitHub account is required.
• A command-line agent already signed in — Claude Code, Codex, or any CLI tool that takes a prompt and prints a final reply.
• About 60 MB of memory at idle for the hub itself; the agents you run are the part that spends tokens.

One warning up front: the project is four days old and its interface is still partly untranslated — CLI output and the default notification strings are in Chinese until the translation lands. The commands below are the same in every language.

Step 1: Install Agent Autoloop#

One command, straight from the README. On macOS or Linux:

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

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.ps1 | iex

The installer fetches the latest release that has passed every check — right now that is 1.6.3, released today. The same goes for agent-autoloop update later: it always installs the newest checked release. Confirm the install took:

agent-autoloop status

That prints the rounds, tokens, and cost for today and the past seven days. With nothing configured yet, expect all three to read zero.

Step 2: Run the guided trial#

Before writing any configuration, run the real loop once with your own agent:

agent-autoloop try

The trial sends an event, your agent does a round of work, then asks you to pick a colour — and exits while it waits. The English README shows the Codex output in a non-interactive terminal (the live CLI still prints it in Chinese for now):

Event sent. The agent is getting to work...

The agent finished this round and asked you a question. No process is running for it now, and it is not spending tokens.

[Your call] #1 Try run: pick a color
This is a try run. Either choice is fine.
  1. Blue
  2. Green
Answer: agent-autoloop answer 1 <number>
After you answer, run agent-autoloop status to see it pick the work back up and finish.

In an interactive terminal, type the number and press Enter. In a non-interactive one, answer by command — agent-autoloop answer 1 2 picks Green. Then run agent-autoloop status again: it shows the agent resuming the same conversation and finishing the trial, plus the rounds, tokens, and cost so far. The point of the exercise is the middle state — while you were deciding, no agent process was running and no tokens were being spent.

Step 3: Write your first rule — a morning brief#

Rules live in ~/.agent-autoloop/rules.json, and writing one needs no glue code: you declare what happened, who handles it, and where they work. This rule has Codex write a morning brief from your notes every day at 9:00:

{
  "name": "Morning brief",
  "when": { "cron": "0 9 * * *" },
  "to": "codex",
  "cwd": "~/notes",
  "prompt": "Summarize yesterday's notes and commits into today's brief."
}

Set to to a name already configured under agents. Changes take effect within seconds of saving. Validate before you trust it:

agent-autoloop check
agent-autoloop check rules-draft.json
agent-autoloop rules explain

check validates the live rules; check <file> validates a draft without touching the running hub; rules explain shows the rules in effect and their next runs. And if you ever save a broken file — or delete it — the hub keeps running the previous valid rules and sends you a card saying so, instead of stopping.

Step 4: Hand it a real event — new GitHub issues#

Schedules are only half the hub. External events work the same way once the source is connected: register github under sources (the configuration manual walks through it), then add a rule that hands every new issue to Codex:

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

The bundled recipe for this polls for new issues every five minutes, edits code locally, and notifies you to review — it never commits, pushes, or replies to the issue itself. If two events arrive for the same issue while one is queued, the hub merges them into a single round instead of starting the agent twice.

Preview what an event would do before it fires:

agent-autoloop emit issues.opened --dry-run

That prints which rule and agent the event would reach, without contacting the hub or writing to the log.

Step 5: Teach the agent to ask you#

The hub asks exactly one thing of an agent: put the result in the final message. A one-line conclusion is enough when the job is done. When the agent needs your call, it appends an agent-autoloop block to that message:

Order checked. We have enough stock in the warehouse.

```agent-autoloop
{
  "ask": [{
    "title": "How should we ship it?",
    "text": "Both options can go out today.",
    "options": ["Courier", "Pickup"],
    "key": "shipping"
  }]
}
```

That block becomes a card on your phone or desktop — desktop notifications are on by default, and Feishu, DingTalk, WeCom, Slack, and Discord are built-in channels. Besides ask, a receipt can send a plain notification (notice), close an open card (resolve), schedule a follow-up check (later), or emit a new event (events). A notice marked fyi carries no buttons at all.

The waiting is the whole trick: while you decide, the agent process has exited and the waiting state sits in a database. Leave a card unanswered for three days and those three days cost you no process and no tokens — answer it, and the hub resumes the original conversation instead of starting over. If the agent's JSON is malformed, the hub has it rewrite just that final message in the same session, without redoing the work; if the rewrite fails too, it keeps the original conclusion and tells you the receipt never applied.

Step 6: Operate it day to day#

Three commands cover daily operation. Pause and resume a rule without editing the file — a paused rule skips its times and ignores events, and resuming does not catch up on what was skipped:

agent-autoloop pause "Morning brief"
agent-autoloop resume "Morning brief"
agent-autoloop run "Morning brief"

run fires the rule once, now. To trace any round — why it ran, what came back — ask the hub:

agent-autoloop why 1

Every state change is derived from an append-only log, so any round's history is one command away. Two safety rails are worth knowing: external text such as issue titles is passed to the agent as files, never spliced into prompts, and event fields that try to override the agent, directory, or permissions are rejected outright. And if agents keep spawning events from each other's replies, a hop counter caps the chain — past eight hops the hub only records the event and sends you a card.

One more built-in: tag a GitHub pull request deliver and the delivery plugin takes it from review through CI, merge, deployment, and a live-version check on its own. Review and delivery configuration are read only from main, and PR code is never checked out or run on the machine that takes the order.

Step 7: Plug in more agents and channels#

Claude Code, Codex, ACP, and DeepSeek Harness (0.2.2 or newer) are built in. Anything else connects in one line: set use: "command", pass the command as an array, and the prompt goes in as its own argument — never executed as shell code. The README compiles these from each project's official docs, and notes they have not each been run yet:

Agents that speak ACP connect with use: "acp" — Gemini CLI as ["gemini", "--acp"], OpenCode as ["opencode", "acp"]. Channels are the same story: desktop notifications are on by default, and Feishu, DingTalk, WeCom, Slack, or Discord take a configuration entry. Third-party plugins install from any git URL:

agent-autoloop add <git URL>

If you would rather run several agents at once than one in the background, Worktrunk runs five coding agents in parallel without merge chaos — the two tools solve opposite scheduling problems.

What you built#

A hub on your own machine that runs your agents while you are not watching: a morning brief every day at 9:00, new GitHub issues routed to Codex, and a card on your phone only when a decision is actually yours. Underneath it is a kernel of about 1,850 lines with zero runtime dependencies — and the measured numbers are small: an 88.78 ms cold start, 59.94 MB of memory at idle, 2,394 persistent writes a second, and a 1.82 ms dispatch p99, measured on an Apple M5 Pro with 24 GB of RAM and Node 24.21.0. Sessions that run for weeks need a different trick — a tool that keeps one conversation alive for weeks — but for getting work dispatched and followed through, the loop is the missing piece.

Honest limitations#

• Young and partly untranslated. CLI output and default notification strings are still Chinese; the recipe instructions are written in Chinese too. Version 1.6.3 fixes two Windows install and stalling bugs — if you run Windows, install the current release, not an older one.
• Not everything is proven. The generic agent commands above are compiled from official docs and have not each been run; the GitLab webhook was tested against the official format, not a real GitLab; the recipes were verified with a local HTTP server and a fake Feishu CLI, not end to end on live accounts.
• Defaults assume a Chinese workday. The feedback, website-watch, Feishu-brief, and inbox-triage recipes default to Asia/Shanghai time and send to a private Feishu chat — adjust the times and the channel before enabling them.
• Durability has a gap. The hub survived 1,000 forced process kills in testing with no confirmed record lost, but whole-machine power loss was not separately tested.
• It spends your money, not its own. Model calls run under your own account and subscription; the README points to API keys for high-frequency automation or serving others, since personal subscriptions are built for interactive use.