Agent Autoloop Turns Claude Code and Codex Into Background Workers That Only Interrupt You for Decisions

A small open-source hub runs your coding agent in the background, exits while it waits for you, and resumes the same session when you tap an answer on your phone.

Most coding agents still assume someone is sitting at the terminal. The agent runs, hits a question, and stops. If you walked away for lunch, the work sits there until you come back and scroll up to find out what it wanted.

That's a strange design for tools that can now work for an hour unattended. The bottleneck isn't the model anymore. It's the human, and specifically the fact that the agent can only reach you through a window you have to be staring at.

Agent Autoloop, an MIT-licensed project that hit v1.0.0 on November 3 and sat at #2 on Trendshift's momentum board this morning, takes a different approach. Your agent works one round and exits. If it needs you, it sends a decision card to your desktop, Slack, Discord or a few other channels. Nothing runs while you think. When you answer, the original session picks back up. Think a 9 a.m. brief written before you're awake, or a new GitHub issue looked at while you're at lunch, with a card only if the agent wants to do something you'd want to approve.

The shift is small and it changes a lot: the agent's natural stopping point becomes a question, not a frozen terminal.

What it is, in plain terms

Agent Autoloop is a hub, a small background program that sits between events and your agent. Events are things like "it's 9 a.m.," "a new GitHub issue came in," or "an alert fired." Rules you write decide which agent handles each event and in which folder. The hub then calls the agent you already have installed and signed in: Claude Code or Codex out of the box, plus a generic plugin for any command-line agent that takes a prompt and prints a reply.

The English README lays out the flow in five steps:

1. An event comes in.
2. Your rules dispatch it to an agent and a folder.
3. The agent works one round, puts its result in its final message, and exits.
4. For sensitive actions, the hub sends you a card, and no agent process runs while you decide.
5. Your answer resumes the original conversation and finishes the job.

There's no web dashboard. You check progress with a command.

The idea worth stealing: end every turn with an answer or a question

Here's the part that makes it work. The agent has one rule to follow: say the result in the last reply. If it needs a human, it adds a small JSON block, fenced with the label agent-autoloop, to the end of that reply. The block can ask a question with options, post a notice, schedule a re-check for later, or emit new events.

Here's a minimal version shaped like the README's example. The schema at v1.0.0 requires a title, a text and two to five options:

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

The hub turns that block into a card with two buttons. You tap one. The hub resumes the agent's session with your answer.

Think of it like leaving a note on a colleague's desk instead of standing behind them until they look up. The colleague goes home. The note waits. In the README's words: "If you reply three days later, no agent process runs and no tokens are spent in the meantime."

That sentence is the reason to care: a waiting agent costs nothing while you're in a meeting.

The README lists the kinds of actions that should trigger a card: deleting data, restarting services, spending money, posting externally. Routine work just finishes.

How it handles the ways this goes wrong

A lot of small agent tools skip the failure cases. This one spends real README space on them, and it's worth knowing what's there before you trust it with anything.

Bad JSON. If the agent's question block is malformed, the hub asks the agent to rewrite only that final block, in the same session, so finished work isn't redone. If the rewrite fails too, it keeps the agent's conclusion and tells you the request didn't go through.

Crashes. All state comes from an append-only event log, a record that only ever grows, written to disk before the hub acknowledges anything. The author says 1,000 forced process kills lost no confirmed records. Power loss was not tested.

Runaway loops. An agent can emit new events, which could trigger the agent again, forever. Each re-dispatched event carries a hop counter the agent can't reset. After 8 hops, the hub stops and sends you a card.

Hostile input. This one matters most. The README says events that try to set the folder, the agent or the permission level are rejected outright. Text from outside, like a GitHub issue body, is written to a file as reference material and never pasted into the prompt. The prompt carries only checked types, IDs and links.

That last design choice is the right instinct. Your rules file decides what an agent may do. An event, which a stranger on the internet may have written, never does. The project's security notes still say prompt injection is possible, and recommend that actions with side effects ask first.

Put this into practice

You need macOS or Linux, Node 24, Git, curl, and at least one agent command-line tool already signed in (Claude Code or Codex is the easy path). No GitHub account required.

1. Install. The README's one-liner:

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

That pipes a script from the internet into your shell, and it pulls from the moving main branch, not the v1.0.0 tag, so what you install next month may differ from what this article describes. If you'd rather read it first (you should), download install.sh, look it over, then run it.

2. Try a real round trip.

agent-autoloop try

This runs one real loop with your own agent: it asks you a question, exits while it waits, takes your decision, and resumes. In a non-interactive terminal you answer with a command; the README's example is agent-autoloop answer 1 2.

3. Check what happened.

agent-autoloop status

You'll see the resumed session plus token and cost stats for today and the past seven days. That cost line is the quickest way to see whether background work is worth it for you.

4. Write your first rule. Rules live in ~/.agent-autoloop/rules.json. A rule has a name, a when (a cron schedule or an event source), a to naming the agent, a cwd folder, and a prompt or a skill. The README's example is a morning brief: every day at 9 ("cron": "0 9 * * *"), send Codex to ~/notes with a prompt to summarize yesterday's notes and commits. Start with something like that, where nothing leaves your machine.

5. Validate before you trust it.

agent-autoloop check

Changes take effect within seconds. If the file is broken, the hub keeps running on the old rules and sends you a card instead of falling over.

6. Add a channel you'll actually see. Desktop notifications are on by default. Webhook templates (ready-made settings for posting messages into a chat app's incoming URL) exist for Slack, Discord, DingTalk and WeCom, and Feishu gets full button support. Text-based channels use reply links, so you need to set hub.publicUrl to an address your phone can open. The hub listens only on localhost by default, and the security notes say to put an HTTPS reverse proxy in front if you expose it.

A good first week: a morning brief rule, then the GitHub issue recipe, which polls every 5 minutes and edits code locally but, per the README, does not commit, push or reply on the issue. That's a safe way to see how often the agent reaches for a card.

Honest limitations

A lot of it is tested against mocks. The README is upfront: the four webhook templates were tested only against a local mock, the GitLab webhook against its documented format, the recipe scripts against a local server and a fake Feishu tool, and the extra command-line agents in its table were not run individually. Expect rough edges once you connect real accounts.

The defaults lean toward China-based teams. Feishu has the deepest support, several recipes use Beijing time, the Chinese README is the primary one, and the README notes that command output and default notification text are in Chinese for now. None of that blocks you, but Slack and Discord users are on the less-tested path.

The benchmarks are one machine. Startup in about 89 ms and about 2,400 durable writes per second are the author's numbers on an Apple M5 Pro, with pass marks tuned to that machine. They tell you the core is small (about 1,650 lines, zero runtime dependencies), not how it behaves on your server.

Unattended means your agent's own permissions are the real limit. The hub maps an access level from your rules to the agent's permissions. The default is edit, and the security notes warn to grant full only after thinking about what the agent can reach. The generic command plugin doesn't restrict what the program does at all. If your agent can push to production, a background agent can too.

Card links are keys. Whoever holds a card's reply link can answer it, and the security notes say links stay valid for 7 days. Don't paste them into a shared channel.

History grows forever. The README says queries over full state slow down as history grows and disk use keeps climbing.

Check your plan's terms. Usage bills to your own account under each vendor's terms, and the README recommends API keys for high-frequency automation. Running a consumer subscription around the clock may not be what that subscription allows.

The shape of agent work is changing

Most agent tooling so far has tried to make the agent run longer. Bigger context, longer sessions, more autonomy. Agent Autoloop goes the other way: make each run short, make the stopping point a clear question, and make waiting free.

That's a pattern you can borrow even if you never install this repo. Give your agents a way to end a turn with "here's what I need from you" and exit, and the cost of walking away from your desk drops to zero.

What would you hand off first if your agent could tap you on the shoulder instead of waiting for you to look?

Sources: KKKKhazix/agent-autoloop README (Chinese) and English README, SECURITY.md, protocol schema, releases (reviewed at tag v1.0.0, released November 3 2026; read November 4), LICENSE (MIT), Trendshift read about 07:20 ET November 4.