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, thenagent-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-sendwas missing; CLIstatus/answerstill finished the loop. - Rules live in
~/.agent-autoloop/rules.json(cron brief, GitHub issues, …). Changes apply within seconds; validate withagent-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 shouldaskfirst.
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:
- An event arrives — a 9:00 cron, a new GitHub issue, or an alert.
- Rules dispatch it —
rules.jsonpicks the agent and working directory; queued events for the same subject merge. - One round, then exit — the final message carries the result; while you decide, no agent process runs.
- Cards only when needed — deletes, restarts, outbound messages, and similar actions ask via Feishu / DingTalk / WeCom / Slack / Discord or desktop notifications.
- 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
| Item | Requirement |
|---|---|
| OS | macOS or Linux. Native Windows pending (#17); per INSTALL, WSL2 works with systemd / linger / notification caveats |
| Runtime | Node.js 24+, Git, curl |
| Agent | At 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
- Sign up at aicodewith.ai, open Key Management.
- Create key, give it a clear name (e.g.
autoloop-box). - Copy the full key immediately; it will not be shown again. See the Create API Key docs.
Codex — global ~/.codex/config.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:
{
"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
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):
Installed.
Agent: Codex
Channel: desktop notifications
Rules: ~/.agent-autoloop/rules.json
agent-autoloop v1.5.0 (commit f211ca2de3b1)
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):
| Step | Time | Result |
|---|---|---|
| agent-autoloop try | 15:25:01 → 15:25:10 | ~9 s, card “Try run: pick a color” (blue / green) |
| agent-autoloop answer 1 2 | 15:25:27 | Chose green; round 3 started on the same Codex session |
| Resume finished | 15:25:27 → 15:25:37 | ~10 s, “you picked green, try run passed” |
| Desktop notify | same time | spawn notify-send ENOENT on this headless box; CLI still worked |
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>
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):
{
"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:
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):
{
"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
accessisedit. Think beforefull. Side effects go throughask. - Card links — possession answers the card for 7 days; never post them publicly.
- Events do not pick the agent — only
rules.jsondecides 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
- Move to Node 24, install Agent Autoloop, wire Claude Code or Codex.
upif needed, thentry→answer→status.- Add cron / GitHub rules;
check+rules explain. - Follow SECURITY on permissions and card links; scrub keys after tests.



