Quick Answer: Command-line agent automation lets tools like Claude Code or Codex pick up tasks, finish them, and follow up without you watching the terminal. Agent Autoloop does this with a small, zero-dependency scheduler. Each turn runs, the process exits, and it sends an approval card to Feishu or your desktop only when a decision is genuinely unclear.
Most people use Claude Code or Codex like a chat window. You type a request, watch the output, answer the follow-up question, and repeat. Close the laptop or walk away, and the work stops dead. That gap is what command-line agent automation is meant to close. Here's what changes when a small scheduler sits between your agent and the rest of your work, and where the trade-offs are.
Why Terminal-Bound Agents Stall
The default workflow assumes a human is present. The agent process stays open, waiting on your keyboard, and the work pauses the moment you leave.
The popular advice is to keep one long session running so the agent holds its context. That works for an afternoon. It breaks for background work, because a session that waits three days ties up a process for three days. Agent Autoloop inverts this. When the agent asks a question, its process exits, and the waiting state goes into a database. When you answer, the tool resumes the original session. The cause and effect is simple: the process exits, so nothing runs while you're away.
The trade-off is real. Resuming only works if the session ID survived. If it doesn't, the project starts a new session, and the agent loses the earlier conversation. Plan for that, especially on tasks where the reasoning matters more than the output.
How One Task Moves Through the Loop
The Agent Autoloop README describes a five-step cycle:
- A new event arrives. A 9 a.m. cron job, a new GitHub issue, or an error report becomes a standard event.
- The rules dispatch it. The kernel decides which agent handles it and in which directory. Messages that pile up on the same task are merged into one turn.
- The turn finishes and the process exits. The agent writes its result in its final reply.
- It asks only when unsure. For actions like deleting data, restarting a service, spending money, or sending external messages, a card goes to you through Feishu or a desktop notification.
- You answer, and it continues. The agent picks up the original conversation and finishes the remaining work.
Routine work never reaches step 4. The agent can finish the job, or schedule a recheck for later, such as 30 minutes from now. That's where most of the value lives. Here's the part people underestimate: a background loop is only useful if it stays quiet when nothing needs you.
Writing a Rule Instead of Glue Code
You don't write glue code. You describe the job in ~/.agent-autoloop/rules.json: what triggers it, which agent takes it, and which directory it runs in. A daily morning brief looks like this:
{
"name": "morning brief",
"when": { "cron": "0 9 * * *" },
"to": "codex",
"cwd": "~/notes",
"prompt": "Summarize yesterday's notes and commits, then write today's brief."
}
External events work the same way, after you register the source. A rule that hands new GitHub issues to Codex sets "when": { "source": "github", "types": ["issues.opened"] } and caps concurrency with "parallel". Changes take effect within seconds, and agent-autoloop check validates the file before you rely on it.
Here's where it gets interesting. If you save a broken file, or the file disappears, the system keeps running on the last good rules and sends you a card about the problem. Your working automation doesn't go down because of a typo.
There's also a deliberate security choice. Events cannot set cwd, agent, or access fields. The project rejects them outright. Your machine decides where work happens and what permissions it has. The event only supplies the trigger.
The Contract Between Agent and Scheduler
The scheduler asks one thing of the agent: put the outcome in the last reply. A finished task gets a plain sentence. A question gets a fenced agent-autoloop JSON block appended to the reply:
Order checked. Stock is sufficient.
```agent-autoloop
\{
"ask": [\{
"title": "Shipping method?",
"text": "Both options can ship today.",
"options": ["Courier", "Pickup"],
"key": "shipping"
\}]
\}
```
The block can also send notices, resolve cards, schedule rechecks with later, or trigger new events with events.
Malformed JSON is the failure you'll hit first. Agents do this constantly, especially with nested quotes. Agent Autoloop asks the agent to rewrite only that final reply, in the same session. If the rewrite fails, the original conclusion is kept and you get a notice that the receipt didn't take effect. The design avoids the costly alternative, which is re-running the whole task. Re-running after a formatting slip is how duplicate deployments and double-sent emails happen.
Four Kernel Mechanisms Worth Knowing
The kernel is about 1,650 lines with no runtime dependencies. It doesn't read the system clock directly, doesn't use random numbers, and doesn't make outbound requests on its own. Plugins connect in, and credentials stay inside those plugins. Four mechanisms do most of the work:
- Zero-cost suspension: Waiting for your reply costs no agent process and no tokens. Only the lightweight middle layer keeps running.
- Event sourcing: All state is derived from an append-only log. Writes are committed to disk before the system acknowledges them. Any turn's history can be explained with
agent-autoloop why <turn>. - Instruction-data separation: External text, such as an issue title or body, is passed to the agent as material in a file. It is never concatenated into the prompt, which is the same principle as SQL parameterization.
- Hop-count circuit breaker: Events an agent emits are counted across dispatches, including through human questions and scheduled rechecks. Past eight hops, the kernel logs the event, stops dispatching, and sends you a card. The agent can't reset that counter.
The project's own testing has limits, and you should know them. It ran 1,000 forced process kills with no lost confirmed records. It did not separately test whole-machine power loss.
What the Numbers Say
The README publishes benchmarks run on an Apple M5 Pro with 24 GB and Node 24.21.0. The thresholds are tuned to that machine, so treat them as a reference point rather than a guarantee.
| Metric | Reported result | What it means for you |
|---|---|---|
| Cold start | 88.78 ms | Launching the scheduler per event adds little latency |
| Idle memory | 59.94 MB RSS | Light enough to leave running in the background |
| 1,000 waiting long-polls | 170.49 MB RSS | Memory grows with waiting connections, predictably |
| Durable writes | 2,394 per second | Each write is committed before it's acknowledged |
| Startup with 1.1M facts | 99.8 ms | Normal startup stays fast as history grows |
The one number to plan around is the rebuild. After a log format change, the project rebuilds state from the full log, which took 43.1 seconds for 1.1 million facts. That's a one-time upgrade cost, not a daily one, but it's worth knowing before you upgrade a long-running install.
Limits, Platform Support, and API Key Trade-offs
Support is narrower than the marketing might suggest. Agent Autoloop runs on macOS and Linux only. The author has said Windows support is pending and tracked in an issue on the repo. Claude Code, Codex, and ACP have been run through multi-turn question-and-resume flows. Feishu was tested for sending, button callbacks, and card updates. The four webhook templates were checked only against a local mock server, and the GitLab webhook was tested against the official format, not a live instance. The README also lists several other CLI agents with their official headless commands, but the author hasn't run those integrations.
Because the scheduler runs on your own machine and needs no cloud server, it only works while that machine is awake and online. That's a feature for privacy and a limit for uptime.
Account usage is the other trade-off. The project calls the command-line tools you've already logged into, so model usage counts against your own account. The README notes that vendors generally recommend API keys for high-frequency automation, because subscription quotas are designed mainly for interactive use. If you're offering this to other people, use an API key. The project is independent and isn't endorsed by Anthropic or OpenAI.
Frequently Asked Questions
What is command-line agent automation?
Command-line agent automation runs an agent like Claude Code or Codex in the background, so it can take tasks, finish them, and check back without a person at the terminal. A scheduler triggers work, the agent exits between turns, and you're contacted only when a decision needs your input. It's useful for recurring jobs, issue triage, and operations alerts.
How do I run Claude Code in the background?
Install Agent Autoloop on macOS or Linux. You'll need Node 24, Git, curl, and a logged-in agent. Run agent-autoloop try to test a full question, answer, and resume cycle. Then add a rule to rules.json that names your agent and working directory.
Why does the agent exit between turns instead of waiting?
Waiting processes hold memory and keep a session open for as long as the wait lasts. When the agent exits and its state lives in a database, nothing runs while you're away. Your reply then resumes the original session. The trade-off is that if the session can't be resumed, a new one starts without the earlier conversation.
Does Agent Autoloop work on Windows?
Not yet. The project supports macOS and Linux, and the author has said Windows support is in development and will ship after compatibility testing. Progress is tracked in the project's GitHub issue.
Command-line agent automation pays off when the work is recurring and the decisions are rare. Install Agent Autoloop on a Mac or Linux machine this week, run agent-autoloop try, and note whether the answer-and-resume loop picked up where it left off. Pass this to anyone whose Claude Code or Codex session dies every time they close the terminal.