How to Use Agent Autoloop: Let Claude Code / Codex Pick Up Work in the Background and Ask You Only When Needed (Install, rules.json, Hands-on)

Agent Autoloop turns Claude Code, Codex, and similar CLI agents into a background loop—events or cron dispatch work, the agent exits after each round, and you get a card only when a decision is yours. This guide follows the official README and SECURITY docs, walks through install plus our measured try → answer → status loop, a morning-brief rules.json example, aicodewith API Key setup, and unattended-security boundaries.

6 分钟阅读
How to Use Agent Autoloop: Let Claude Code / Codex Pick Up Work in the Background and Ask You Only When Needed (Install, rules.json, Hands-on)

Up front:

  • Agent Autoloop (MIT) replaces “babysit a terminal” with “event / cron dispatch → agent finishes one round and exits → card only when needed → your answer resumes the same session.” The official README covers macOS / Linux; a native Windows build is still pending (issue #17; the README says WSL2 works for now).
  • One-line install: curl -fsSL https://raw.githubusercontent.com/KKKKhazix/agent-autoloop/main/install.sh | sh, then agent-autoloop try.
  • We measured on Linux on 6 November 2026: Node 24.22.2, agent-autoloop v1.5.0, Codex with an aicodewith key (gpt-6.1-sol). The approval loop worked—about 9 s to the color card, then after answering “green” about 10 s on the same session to “try run passed.” With no desktop session, notify-send was missing; CLI status / answer still finished the loop.
  • Rules live in ~/.agent-autoloop/rules.json (cron brief, GitHub issues, …). Changes apply within seconds; validate with agent-autoloop check.
  • Unattended means local permissions: do not share card links; authenticate webhooks. Per SECURITY, prompt injection is not fully solved—default access is edit; side effects should ask first.

Create an API Key, wire Claude Code / Codex, then run the background loop →

What problem it solves

Most people use Claude Code or Codex by watching a terminal. Close the window and the work stops.

Agent Autoloop centers on a deterministic kernel (about 1,650 lines, zero runtime deps per the README) with swappable plugins for events, agents, channels, and delivery:

  1. An event arrives — a 9:00 cron, a new GitHub issue, or an alert.
  2. Rules dispatch it — rules.json picks the agent and working directory; queued events for the same subject merge.
  3. One round, then exit — the final message carries the result; while you decide, no agent process runs.
  4. Cards only when needed — deletes, restarts, outbound messages, and similar actions ask via Feishu / DingTalk / WeCom / Slack / Discord or desktop notifications.
  5. One answer resumes — work continues in the original conversation.

Per the README, Claude Code, Codex, and ACP (with the official Codex ACP adapter) have been run through multi-turn Q&A and cross-process session resume; Feishu has real delivery and button callbacks. Webhook templates and GitLab payloads were checked against local mocks / docs—not always live accounts.

Prerequisites

ItemRequirement
OSmacOS or Linux. Native Windows pending (#17); per INSTALL, WSL2 works with systemd / linger / notification caveats
RuntimeNode.js 24+, Git, curl
AgentAt least one signed-in Claude Code or Codex (or another CLI via command)
aicodewith key (optional)Register and create an API Key if you bill models through aicodewith

Our box started on Node 22; after n 24 → 24.22.2, install succeeded. agent-autoloop doctor checks the major version.

Step 0: Create an API Key

  1. Sign up at aicodewith.ai, open Key Management.
  2. Create key, give it a clear name (e.g. autoloop-box).
  3. Copy the full key immediately; it will not be shown again. See the Create API Key docs.

Create API Key →

Codex — global ~/.codex/config.toml:

toml
model = "gpt-6.1-sol"
model_provider = "aicodewith"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "YOUR_API_KEY"

Claude Code — ~/.claude/settings.json:

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aicodewith.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY"
  }
}

New to Codex? See Codex install, Codex API Key config, and Codex config.toml. For background subagents see Claude Code background subagent status. For parallel worktrees after Conductor’s shutdown, see Conductor alternative: git worktree.

Install

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

The app lands in ~/.agent-autoloop/app, data under ~/.agent-autoloop, with a link in ~/.local/bin when possible. For CI / headless / temp HOME, use --no-service per INSTALL, then agent-autoloop up.

Our run (2026-11-06, Asia/Shanghai):

text
Installed.
  Agent: Codex
  Channel: desktop notifications
  Rules: ~/.agent-autoloop/rules.json
agent-autoloop v1.5.0 (commit f211ca2de3b1)
bash
agent-autoloop --version
agent-autoloop doctor
agent-autoloop up          # if you used --no-service
agent-autoloop try

Minimal loop: try → answer → status

try emits a local trial event. In a non-interactive terminal it prints the question and an answer command, then exits—that wait is expected.

Our Codex timeline (UTC+8):

StepTimeResult
agent-autoloop try15:25:01 → 15:25:10~9 s, card “Try run: pick a color” (blue / green)
agent-autoloop answer 1 215:25:27Chose green; round 3 started on the same Codex session
Resume finished15:25:27 → 15:25:37~10 s, “you picked green, try run passed”
Desktop notifysame timespawn notify-send ENOENT on this headless box; CLI still worked
text
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.

[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>
bash
agent-autoloop answer 1 2
agent-autoloop status
agent-autoloop why 3

why 3 showed trigger card.answered, the same codex://threads/... session, and the pass line.

Honest notes: the first try failed because the Codex model id was not listed on aicodewith; after setting model = "gpt-6.1-sol" it passed. Claude Code got a separate smoke test with the same key (~6 s → OK); this try loop used the Codex plugin.

Write rules.json

Under rules, declare when / who / where. to must match an entry in agents.

Morning brief (from the official README):

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

We temporarily added an equivalent rule:

bash
agent-autoloop check
agent-autoloop rules explain

check reported OK; rules explain listed Asia/Shanghai and “Morning brief: daily 09:00 (next 11/07 09:00) → codex”.

GitHub issues sample (register github under sources first):

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

More recipes (brief, issues, alerts, feedback, site watch, Feishu weekly, PR delivery) ship in the repo.

Claude Code, Codex, and other CLIs

Built-in use values include claude, codex, acp, dsh, or command with {prompt} as a single argv (never shell-interpolated). Per the README, Claude Code / Codex / ACP have multi-turn + resume coverage; Cursor CLI, pi, OpenClaw, Hermes, CodeBuddy samples come from each tool’s docs and are not all hand-tested by the author.

Autoloop is event-driven background looping—not the same as many parallel worktrees. For the latter, see the Conductor alternative. Claude Code / Codex / Cursor are peer options; plug in what you already run.

Security boundaries

From SECURITY and the README terms section:

  • Local privileges — the loop runs as your user; default access is edit. Think before full. Side effects go through ask.
  • Card links — possession answers the card for 7 days; never post them publicly.
  • Events do not pick the agent — only rules.json decides agent, cwd, skill, and access. External text is filed as data, not raw prompt glue—but that does not stop all prompt injection.
  • Webhooks / channels — put HTTPS in front; webhook templates have no external idempotency guarantee; authenticate chat apps; keep private feedback off shared groups.
  • Credentials — the hub does not read or proxy Claude Code / Codex logins. Prefer API keys for automation over personal subscription quotas (per typical Anthropic / OpenAI guidance).
  • Cleanup — after testing, delete key-bearing config and logs; a full-disk search for key fragments should return 0.

Secondary write-ups (explainx.ai, karmazinmedia, etc.) are fine as “as reported”; treat README / SECURITY / INSTALL as source of truth.

FAQ

Does Windows work?

Native support is pending (#17, planned work around 7–8 Nov per README). INSTALL documents WSL2 today.

Do I need a system service?

No. Use service install when you want login persistence; otherwise --no-service + agent-autoloop up.

try failed / model error?

Run doctor. Confirm Node ≥ 24, hub up, agent online. On aicodewith, pick a model from the pricing / model list and a complete experimental_bearer_token. Our first failure was a missing model id.

How is this different from many terminals?

You babysit terminals; Autoloop only starts a round when an event fires and exits while waiting on you. For GUI multi-worktree parallel work, combine with worktree tools as needed.

Wrap-up

  1. Move to Node 24, install Agent Autoloop, wire Claude Code or Codex.
  2. up if needed, then try → answer → status.
  3. Add cron / GitHub rules; check + rules explain.
  4. Follow SECURITY on permissions and card links; scrub keys after tests.

Create an API Key and write your first background rule →

相关文章

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

The UI SDK is Vercel's behavior library for agents, released on 12 November 2026 as 0.1.0-beta.1. Behaviors live in the framework-free @ui-sdk/core package and are rendered by adapters for React, Vue, Svelte, Solid, and Web Components. This guide follows the official docs on what it is, how to install it, and how to add the skill for Claude Code, Codex, and Cursor, and it records the commands, timings, and output from our test machine.

What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

AWS Emulator is AWS's official local emulator of its service APIs, generally available since November 11, 2026 (US time). It has no additional service fee, its source is open, it needs no AWS account, and it covers more than 200 services. We tested version 1.0.322 on Debian 13. This guide covers the install commands, pointing the AWS CLI at the local endpoint to create an S3 bucket and a DynamoDB table, the errors we hit, and how to let Claude Code, Codex and Cursor write and test code against the emulator.

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

T3 Code is pingdotgg's open-source control surface for coding agents. It ships no model of its own; it drives the Claude Code, Codex, Cursor and other CLIs already on your machine. We tested T3 Code 0.1.9 on Linux. This guide covers the install commands, how to point Claude Code and Codex at an AICodeWith API Key so T3 Code can drive them, a full run of both agents with the t3 thread command, and the errors we hit along the way with their fixes.