RSS
Built with Claude

Agent Autoloop: run Claude Code and Codex in the background and get a card when they need you

Agent Autoloop is a self-hosted, zero-dependency hub that runs Claude Code, Codex and other CLI agents in the background, and sends you a card when a decision is yours or something needs attention. Install steps, first rules and the project's own security limits.

Server rack with blinking green lights illustrating Agent Autoloop running coding agents in the background
Photo by Domaintechnik on Unsplash

KKKKhazix/agent-autoloop is a self-hosted hub that runs command-line agents such as Claude Code and Codex in the background. Events (a cron time, a new GitHub issue, an alert) go to the hub, rules pick the agent and folder, and the agent works one round and exits. When it needs a human call, it ends the round with a question; the hub sends you a card on desktop, Feishu or a chat webhook and resumes the same conversation after you answer. Cards also carry notices, such as a broken rules file or a stopped event chain. The repo was created on 2026-11-03 and had 5,491 stars as of November 16, 2026.

Quick facts

  • Repo: github.com/KKKKhazix/agent-autoloop, MIT licence, written in TypeScript.
  • Platforms: Windows (native since v1.6.0, per its release notes), macOS and Linux; WSL2 installs as Linux.
  • Requirements: Node.js 24 or newer, Git, and a command-line agent you are already signed into; curl on macOS/Linux.
  • Runtime dependencies: none. package.json lists only dev tools (TypeScript, Prettier, Node types).
  • Cost: the tool is free; model usage is billed to your own agent account.
  • Releases: 22, from v1.0.0 (2026-11-03) to v1.8.5 (2026-11-15).

How to install

The official install is a one-line script that fetches the newest release, which the README says has passed every check. It pipes a remote script into your shell, so read install.sh or install.ps1 and the Releases page first; INSTALL.md also covers installing from a local clone.

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

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

The program goes into ~/.agent-autoloop/app; rules, keys and records stay in ~/.agent-autoloop. On macOS and Linux the installer registers a background service that starts at login, and it does not use sudo. On Windows it uses a per-user Task Scheduler login task and needs no admin rights. Without a service manager, pass --no-service and run agent-autoloop up yourself.

Known snags from INSTALL.md: Homebrew's node@24 is not on PATH by default; Windows' built-in Administrator account with UAC on gets a Startup-folder command instead of a login task; listen EACCES usually means Hyper-V or WSL reserved the port; WSL2 notifications do not reach the Windows desktop. SECURITY.md adds that Codex's Windows sandbox can read the master key and config secrets until the hub starts.

INSTALL.md is written to be handed to an agent. agent-autoloop update moves to the latest release; agent-autoloop uninstall removes the program but keeps your rules, keys and records.

First setup

No GitHub account is needed to install. You do need one agent CLI already signed in; the installer detects what you have, or you choose with --agent claude, --agent codex, or --command for another CLI. GitHub issue polling and PR delivery additionally need a signed-in gh.

agent-autoloop --version
agent-autoloop doctor
agent-autoloop try

try runs a real loop and uses your model quota. The agent asks you to pick a colour, the round ends, and no agent runs while it waits. Answer with agent-autoloop answer <card> <option> (answer 1 2 in the README example), then agent-autoloop status shows the resumed conversation plus rounds, tokens (cache included, share shown) and cost for today and the last 7 days.

Then write rules in ~/.agent-autoloop/rules.json: the trigger (cron, or source and event types), to (an agent defined under agents), cwd and a prompt or skill. Permissions come from access on the agent definition, edit by default. agent-autoloop check <file> validates a draft without touching the running hub, and rules explain shows next run times. If the file breaks, the hub keeps the last valid rules and sends you a card. Without Feishu or a webhook, cards only appear as desktop notifications and in status.

README recipes to start from: morning brief, GitHub issues, production alerts, user feedback, website watch, Feishu weekly brief, inbox triage and PR delivery. Several default to Asia/Shanghai time and the owner's private Feishu chat.

Day to day: pause, resume and run <rule>; replay <rule> --since <time> catches up events skipped while paused; why <round> explains a round. backup and restore cover hub.db and master.key, which signs card links, so losing it breaks issued links. To answer from a phone, run the hub on a server with hub.listen at 127.0.0.1:3350, set hub.publicUrl and add an HTTPS reverse proxy.

What stands out

  • Waiting costs no tokens. When the agent asks, its process exits and only the lightweight hub keeps waiting, with state in SQLite. Answer three days later and your answer resumes the original session.
  • External text stays out of the prompt. Issue titles and bodies go into a local data file; the prompt carries only checked types, IDs and links. That reduces prompt injection but does not stop it. Only rules.json decides which agent runs, where and with what access.
  • A hop limit stops runaway chains. Agent-emitted events can trigger more agents, but the hop count survives questions and follow-ups and cannot be reset by the agent. Past 8 hops the hub stops dispatching and sends a notice card.
  • Every round is traceable. State is rebuilt from an append-only fact log, and why <round> prints the rule version, trigger, worker and outcome, though not each step inside the agent's CLI. A shipped check kills the process 1,000 times and verifies no acknowledged record is lost.

The agent's side is small: it ends its final message with a fenced agent-autoloop JSON block that asks a question, sends a notice, schedules a follow-up, resolves cards or emits events.

An optional delivery plugin takes a PR labelled deliver through review, CI, merge, deployment and a live-version check. It reads trusted settings from main and reviews a read-only snapshot without running the PR's code.

What the commit history shows

In our snapshot of main on 2026-11-15, 156 of 224 commits carried a Claude co-author trailer (152 Claude Opus 5.5, 4 Claude Fable 5.2). A trailer records attribution, not how much work Claude did, and the counts grow daily. GitHub lists 34 contributors.

AGENTS.md is a rule file for agents that change the repo. Tests come before implementation, and a bug fix starts with a failing test. The kernel must not make outbound requests, read the clock or know product names, which a purity test enforces, and package.json may not have dependencies. Kernel, worker, protocol and host PRs are reviewed by an agent that did not write them, and releases are tagged only after a nightly 200,000-step simulation plus kill and mutation checks.

Try it with your AI. Copy this into Claude Code, Codex or another agent to install Agent Autoloop and set up one background rule. It checks prerequisites first and stops for your confirmation before anything that installs, spends tokens or writes config.

I want to try KKKKhazix/agent-autoloop on this machine so a command-line agent can
handle [the job I want automated, e.g. a morning summary of ~/notes] in the background
and ask me when a decision is mine.

First check and report: the output of node --version (it needs 24 or newer) and git
--version. Do not log in for me and do not read or copy any credential files.

Then:
1. Show me the official install command from the project README for my OS. Before
   running it, fetch install.sh (or install.ps1 on Windows) without executing it,
   summarise what it does, and confirm the latest tag on the Releases page. Wait for my
   confirmation.
2. Run agent-autoloop --version and agent-autoloop doctor (doctor checks whether my
   agent CLI is signed in) and summarise the results.
3. Tell me that agent-autoloop try uses my model quota, and run it only after I confirm.
   If it asks a question, relay it to me, then run agent-autoloop answer <card> <option
   number> with the card number it shows and my choice, then agent-autoloop status.
4. Draft one rule with name, when (a cron expression or source and types), to (an agent
   name already defined under agents in rules.json), cwd (an existing folder: [folder])
   and either prompt or skill. Keep that agent's access at "edit" or lower, never
   "full"; if it uses the generic command plugin, tell me access does not restrict it.
   Save the draft to a separate file, run agent-autoloop check <draft file> and
   agent-autoloop rules explain <draft file>, show me the result and next run time, and
   only merge it into ~/.agent-autoloop/rules.json after I confirm.

Do not add channels that send messages to other people, do not share card links, do not
run uninstall, and do not delete any files.

Known limits

  • Prompt injection is reduced, not solved, per SECURITY.md: the agent still reads outside text. Default access is edit; think hard before granting full.
  • askFirst is only a prompt instruction; the hub cannot block an agent that ignores it. Only access and the agent's own sandbox enforce limits, and with the generic command plugin access restricts nothing.
  • No isolation inside one OS account: read access does not stop an agent reading secrets on the machine. Use a separate account or container.
  • Card links are bearer tokens valid for 7 days, so keep them out of public pages and shared chats. The hub listens on localhost by default.
  • Uneven test coverage, stated in the README: Claude Code, Codex and ACP have run multi-turn resumption, but the DingTalk, WeCom, Slack and Discord templates were checked only against local mock servers, and the business recipes only with local HTTP and a fake Feishu CLI.
  • Crash safety covers process kills, not power loss, and the project says it is not a full security audit.
  • Provider terms: providers generally recommend API keys over personal subscriptions for automated work, and the README says to use API keys if you run it for others. The project is independent of Anthropic and OpenAI.
  • Young project: under two weeks old, 22 releases, no long-term support branch or promised response time.

Problems and feedback

Bugs and feature requests go to GitHub Issues (CONTRIBUTING.md links the new-issue page). On 2026-11-15 there was 1 open issue and 59 closed, plus 4 open PRs. Report security problems privately through GitHub Security Advisories.

FAQ

Does it need a server or open ports? No. It runs on one machine with no cloud server and no inbound ports. Link-based channels need hub.publicUrl reachable from your phone, ideally behind an HTTPS reverse proxy.

Which agents work with it? Built-in plugins cover Claude Code, Codex, ACP, DeepSeek Harness and ZCode; other CLIs connect as a command array. Gemini CLI and OpenCode answered the ACP handshake, but multi-turn use has not been run.

Can I use my Claude or ChatGPT subscription? The hub starts CLIs you are signed into and never reads their credentials, but providers generally prefer API keys for automated workloads, and the README says to use API keys if you run it for others.

Is the interface in English? Not yet. The README is in English, but CLI output, default notifications and recipe instructions are in Chinese.

How do I stop a rule or a round? agent-autoloop pause <rule> stops a rule (add --until to resume automatically) and resume brings it back, listing any events it skipped; replay catches them up. agent-autoloop stop <round> stops one running round.

Source: KKKKhazix/agent-autoloop on GitHub, Agent Autoloop README (English), Agent Autoloop installation guide, Agent Autoloop security boundaries, Agent Autoloop development rules (AGENTS.md), Agent Autoloop plugin guide, Agent Autoloop releases, Agent Autoloop commit history

This story first appeared in the claudefox daily briefing for November 16, 2026.