How to Run CLI Agents on Autopilot with Agent Autoloop

Introduction

Most command-line agents work only while you watch them. You type a prompt, stare at the terminal while it runs, and answer its next question. Close the window or walk away, and the job stops. That pattern wastes the best property of an agent, which is doing long, boring follow-through work without you.

Agent Autoloop fixes the waiting problem. It is a self-hosted hub that turns CLI agents into background workers: events come in, rules decide which agent handles each one, the agent runs one round and exits, and you only get involved when something genuinely needs a human decision. This tutorial shows how to install it, run its built-in trial, write your first rule, and use its ready-made templates, plus the honest limits you should know before trusting it with real work.

Quick answer

Install Agent Autoloop on macOS or Linux, verify it with agent-autoloop try, then add a rule to ~/.agent-autoloop/rules.json mapping an event to an agent. Answering an approval card resumes the original conversation.

Evidence

Agent Autoloop is very new, and its early traction is unusually fast for a niche developer tool. The repository, KKKKhazix/agent-autoloop, was created on November 3, 2026, and had already reached 2,447 stars and 490 forks by November 5, with 69 commits and an MIT license. That growth rate alone does not prove quality, but the README is unusually honest about what has and has not been tested, which is a better signal than the star count.

The project describes its core as a zero-runtime-dependency kernel of about 1,651 lines, and it publishes concrete benchmark numbers measured on an Apple M5 Pro with 24 GB of memory and Node 24.21.0: cold start 88.78 ms, idle memory 59.94 MB RSS, 1,000 simultaneous waiting long polls at 170.49 MB RSS, persistent writes at 2,394 records per second, and dispatch at a p99 of 1.82 ms. Those numbers matter because the hub is meant to sit idle for days waiting on human answers, and an idle footprint near 60 MB makes that cheap.

The design rests on four mechanisms the README names explicitly. First, suspended work costs nothing: when the agent asks you a question, its process exits and the waiting state lives in a database, so no tokens burn while you think. Second, event sourcing: every state change comes from an append-only log written in the same transaction as its index, so a killed process loses nothing it already confirmed. Third, separation of instructions and data: external text such as issue titles is passed to the agent as file data, never spliced into the prompt, and event fields that try to override the agent, working directory, or permissions are rejected. Fourth, a hop fuse: agent-generated events that chain into more agent work count up through layers, and past 8 layers the hub only records the event and notifies you instead of dispatching more work.

If you already use approval gates in workflow tools, the pattern will feel familiar: our n8n Agent Builder human-in-the-loop approval tutorial covers the same idea inside n8n, where a workflow pauses for one human decision and then continues. Agent Autoloop applies that idea to CLI agents running on your own machine.

Prerequisites

You need a Mac or Linux machine, Node 24, Git, and curl. You also need at least one command-line agent already installed and logged in, such as Claude Code or Codex, because the hub calls your existing tools rather than shipping its own model access. No GitHub account is required for the basic install, and you do not need a cloud server or a public port. Windows is not supported yet, so Windows users should wait for the release the author has planned for the weekend of November 7 to 8, 2026. Finally, read the English README once before installing, since it documents the exact approval flow and the testing limits better than any summary can.

Step-by-step

1. Install the hub

Run the install script from the repository:

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

The full installation guide covers manual setup if you prefer not to pipe a script into a shell. Either way, the result is a local agent-autoloop command plus an app directory under ~/.agent-autoloop/app. Keep that directory intact, since it holds the kernel, the host shell, and the built-in plugins.

2. Run the built-in trial

Before wiring up anything real, prove the loop works end to end with the command from the README:

agent-autoloop try

The trial sends an event, lets your local agent work one round, and then asks you a trivial question, such as picking a color. While it waits, the agent process exits and consumes nothing. Answer with agent-autoloop answer 1 <number>, then run agent-autoloop status to see the hub resume the same session and finish the trial, along with today’s and the last seven days’ round, token, and cost counts. If this trial does not complete, do not proceed to real rules: the trial exercises the exact path, event, dispatch, question card, answer, and resume, that every later job will use.

3. Write your first rule

Rules live in ~/.agent-autoloop/rules.json, and each rule states what happens, who does it, and where. No glue code is needed. A daily brief rule looks like this, adapted from the README example:

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

The fields are deliberately small. when can be a cron schedule or an event source, to names an agent you have configured, cwd sets the working directory, and prompt is the job. Save the file and it takes effect within seconds. Run agent-autoloop check to validate it. One forgiving detail: if you break the file or delete it, the hub keeps running the previous rules and sends you a card telling you something is wrong, instead of silently stopping.

4. Connect an event source

Cron rules cover scheduled work, but the hub becomes much more useful when external events can start jobs. Built-in event plugins include GitHub webhooks, GitLab webhooks, a plain HTTP endpoint, cron schedules, and an issue polling script. For example, a rule that triggers on a newly opened GitHub issue hands the issue to Codex in your project directory, with an optional skill and a parallelism limit:

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

Note the honesty clause in the README: the webhook templates were validated against local mock services, and the GitLab webhook was tested against the official format without connecting to a real GitLab instance. For your first event-driven rule, use the issue polling script or a GitHub webhook pointed at a test repository, and watch one full cycle before pointing it at anything you care about.

5. Use a ready-made template

The repository ships templates that bundle a rule, a task skill, and setup notes, so you do not have to design the approval flow yourself. The current set includes a daily brief, GitHub issue follow-up, online alert triage, user feedback handling, website patrol, a Feishu weekly report, and PR delivery. To enable one, copy its skill into your agent’s skills directory, merge its sample rule into rules.json with your own machine name and paths, and run agent-autoloop check.

The website patrol template is a good second job after the daily brief: it checks site status and key content every five minutes, hands the first anomaly to an agent, suppresses repeat notifications while the problem continues, and updates the original card when the site recovers. That is exactly the shape of job where the hub earns its keep, because the polling is frequent, the anomalies are rare, and the human only appears when something is actually wrong. If you use Claude Code heavily, our Claude Code MCP setup tutorial pairs well here, since the same agent skills and tool wiring carry over.

6. Handle approvals the way the hub expects

The approval contract is the part most worth understanding before you scale up. The hub makes exactly one demand of the agent: put the result in the final reply. When the agent needs a human, it appends an agent-autoloop code block to that reply, listing questions, notices, or follow-up events as structured data. The hub turns each question into a card in your configured channel, which by default is a desktop notification, with Feishu, DingTalk, WeCom, Slack, and Discord also available.

While you decide, nothing runs and nothing bills. When you answer, the hub resumes the original conversation rather than starting a fresh one, so the agent keeps its context. If the agent writes malformed JSON in its reply block, the hub asks it to rewrite just that block in the same session instead of redoing the finished work, and if the rewrite also fails, it keeps the original conclusion and notifies you that the receipt did not take effect. Actions that need approval include deleting data, restarting services, spending money, and sending external messages, so a compromised or confused agent cannot quietly escalate on its own.

7. Inspect any job after the fact

Every round leaves a trail you can query. agent-autoloop why 1 explains why a given round ran and what it produced, which is the first command to reach for when a job behaves unexpectedly. The repository also ships simulations, including a 200,000-step random simulation of network loss, packet loss, crashes, and duplicate submissions, and a 1,000-kill crash test asserting that no confirmed record is lost. You do not need to run those yourself, but their existence is a useful check on a two-day-old project: the author is testing durability claims rather than just asserting them.

Troubleshooting

The trial hangs or the agent never answers. Check the basics first: Node 24 is installed, your agent CLI is logged in, and agent-autoloop check passes. The hub calls the agent tool you already have, so a login that expired in Claude Code or Codex looks like a hub failure when it is actually an agent authentication failure. Run your agent directly once, confirm it answers, and then retry the trial.

A rule change does not take effect. Rules reload within seconds, but a malformed rules.json leaves the previous rules running by design, with a notification card telling you about the problem. Run agent-autoloop check to find the error, and check your notification channel for the card. Do not assume a silent save means a successful reload.

An agent keeps looping on generated events. This is what the hop fuse is for. Agent-created events chain through layers, and past 8 layers the hub stops dispatching and notifies you. If you hit the fuse, inspect the chain with agent-autoloop why on the recent rounds, find the step that keeps emitting new events, and tighten that job’s prompt or add an explicit stop condition before raising any limit.

A webhook rule never fires. Remember the testing caveat: the webhook templates were validated locally, not against real production accounts. Verify the public URL configuration first, since chat-channel approvals need a hub.publicUrl that your phone or computer can actually open, then test against a throwaway repository before trusting the rule with real issues.

Conclusion

Agent Autoloop is a small, sharp idea executed with unusual transparency for a project that is two days old: a zero-dependency kernel, an explicit approval contract, and published benchmarks alongside candid notes about what has only been tested locally. That combination makes it worth trying now for personal automation, especially if you already live in Claude Code or Codex and want background jobs that only interrupt you when a decision is real. Start with the trial, then a daily brief, then one event-driven rule on a test repository, and let the approval flow prove itself before you hand it anything that can delete data, spend money, or message other people. For a related but heavier approach to autonomous agents, our DeepSeek superagent prototype evaluation tutorial shows the same caution applied to a research prototype: test in a sandbox first, and treat early numbers as claims to verify, not promises.

Frequently asked questions