Running Claude Code in a Loop: The Script That Turns It Into a Persistent Agent

Claude Code is built for interactive sessions. You type, it acts, the conversation ends. That is the right shape for a developer at a keyboard. It is the wrong shape for an agent that needs to keep watch on something. A queue. An inbox. A file. A webhook. A remote service.

To turn Claude Code into a persistent worker you wrap it in a loop. This post is the wrapper.

I will start with the fifteen-line shell version that gets you running in a minute, then walk through the persistent stream-json version that you actually want for anything beyond a demo. The full script is at the bottom.

Why not just spawn claude -p every tick?

The naive shape of a polling agent is to spawn a fresh claude -p process each tick, send a prompt, read the output, and exit. It works on a whiteboard. In practice the cold-start cost is brutal:

• MCP servers handshake on spawn. A multi-second cost on every tick, every time.
• CLAUDE.md and the skill catalogue have to be re-read and re-cached.
• Session transcripts fragment into tiny files that are hard to reason about.
• A 20-second polling interval becomes 30 seconds with cold-start tax.

A persistent session keeps everything hot. One claude process per agent, stdin open, ticks become user-prompt-submit events against an already-loaded session.

The fifteen-line version

When you just want to see the loop work:

#!/usr/bin/env bash
# agent-loop.sh
set -euo pipefail

INTERVAL="${INTERVAL:-60}"
TICK_PROMPT="Call list_dms. For every unread message, read_dm it,
do the work, then reply with send_dm. Empty inbox? Exit quietly."

while true; do
  echo "[$(date +%H:%M:%S)] tick"
  claude -p \
    --mcp-config .mcp.json --strict-mcp-config \
    --dangerously-skip-permissions \
    "$TICK_PROMPT"
  sleep "${INTERVAL}"
done

Make it executable, run it. That is a working agent.

A few things worth calling out before we move on, because they apply to both the simple and the persistent versions:

The TICK_PROMPT is the heart of the script. Make it imperative and name the tools you want called. Do not write "follow your CLAUDE.md". Write "call list_dms" or "pop one job from the queue with queue_pop". CLAUDE.md is for context. The tick prompt is for the action you want this tick.

The reset between ticks is what makes the loop reliable. Each tick of the simple version is a fresh process, so the previous turn is in another universe. Whatever the new prompt names is what the agent does. Without that reset, an agent that finishes a task simply sits there waiting.

Scope through .mcp.json. --dangerously-skip-permissions is fine because there is no human at this terminal, but the agent still only has the tools you give it via MCP. Choose those carefully.

The simple version costs you several seconds of cold-start per tick and re-handshakes every MCP server. For one-minute polling it is fine. For sub-second responsiveness, you want the persistent version.

The persistent version: stream-json on stdin and stdout

The Claude CLI supports a stream-json mode where each user message is one JSON line on stdin and each event is one JSON line on stdout. The wrapper spawns claude once and feeds prompts forever.

The invocation:

claude --print --verbose \
       --input-format stream-json --output-format stream-json \
       --include-partial-messages \
       --dangerously-skip-permissions \
       --mcp-config .mcp.json --strict-mcp-config

Flags that matter:

• --print: non-interactive, no TTY.
• --input-format stream-json: every user message is one JSON line on stdin.
• --output-format stream-json: every event (system init, assistant delta, tool use, result) is one JSON line on stdout.
• --include-partial-messages: keep deltas queryable in case you want them later.
• --dangerously-skip-permissions: no human to approve. Scope through .mcp.json instead.
• --strict-mcp-config: fail loudly when .mcp.json is malformed.

Stdin and stdout framing

Input. One JSON line per user message:

{"type": "user", "message": {"role": "user", "content": "<prompt>"}}

Output. Three event types matter for the loop:

• {"type": "system", "subtype": "init", "session_id": "<uuid>"} captured once per spawn. Used for --resume <uuid> on crash recovery.
• {"type": "result", ...} the turn is complete. The wrapper stops waiting and the tick returns.
• {"type": "__eof__"} sentinel the wrapper enqueues when stdout closes. Triggers a respawn.

All other event types (tool use, partial messages, content deltas) are drained or surfaced as needed.

/clear between completed tasks

Conversation history accumulates inside the persistent session. Left unchecked, that bloats every tick and costs tokens. The fix is the /clear slash command. Send it as a user message between completed units of work. It drops the conversation but keeps MCP servers, skills, and the parsed CLAUDE.md loaded.

The pattern: the agent touches a control file (.orchestrator/clear-session) when it finishes a task. The wrapper checks for that file before each tick. If present, it sends /clear first, then unlinks the file. Same effect as the cold-start reset in the simple version, with all the parsed context still hot.

Backoff sleep

A good loop is cheap on quiet days and responsive when there is traffic. Three knobs:

• MIN_SLEEP = 60: sleep after a productive tick.
• IDLE_STEP = 60: added per idle tick.
• MAX_SLEEP = 3600: ceiling.

If the last tick did meaningful work, reset sleep to MIN_SLEEP. Else add IDLE_STEP, capped at MAX_SLEEP. The agent itself signals "did work" by touching .orchestrator/did-work during the tick.

Signals

Two signals matter:

• SIGUSR1 is wake. The wrapper sets an event; the next sleep wakes immediately. In-flight ticks ignore it. Send SIGUSR1 to the wrapper pid (not the process group) so an in-progress turn is not disturbed. This is how a webhook receiver pokes the agent: write the event to a file, send SIGUSR1, the agent picks it up on its next tick.
• SIGTERM and SIGINT are shutdown. Set a stop event, exit the sleep, send /exit to Claude, wait up to 30 seconds, then kill.

Crash recovery via --resume

If the claude subprocess dies mid-loop, the stdout pump enqueues __eof__, the tick returns None, and the wrapper respawns. If a session_id was captured before the crash, the respawn includes --resume <session_id> so the conversation continues rather than starting fresh.

The complete script

About 130 lines of Python, no third-party dependencies. Drop it next to your .mcp.json and CLAUDE.md.

#!/usr/bin/env python3
"""agent-loop.py - persistent Claude Code polling loop.

Spawns one `claude` subprocess in stream-json mode, feeds it a tick
prompt at exponentially-backed-off intervals, and respawns on crash.
"""
import json, os, signal, subprocess, sys, threading, time
from pathlib import Path
from queue import Queue, Empty

ORCH = Path.cwd() / ".orchestrator"
ORCH.mkdir(exist_ok=True)

MIN_SLEEP = int(os.environ.get("MIN_SLEEP", "60"))
IDLE_STEP = int(os.environ.get("IDLE_STEP", "60"))
MAX_SLEEP = int(os.environ.get("MAX_SLEEP", "3600"))
RESULT_TIMEOUT = int(os.environ.get("RESULT_TIMEOUT", "600"))

# Replace this with the actual work for your agent. Name the tools.
# E.g. for an AgentDM inbox watcher:
#   "Call list_dms. For every unread message, read_dm it, do the
#    work it asks for, then reply with send_dm. If the inbox is
#    empty, exit quietly without printing anything."
TICK_PROMPT = (
    "<your imperative tick prompt here>. "
    "If you did meaningful work, touch .orchestrator/did-work. "
    "If you finished a task, touch .orchestrator/clear-session."
)

stop_event = threading.Event()
wake_event = threading.Event()


class ClaudeAdapter:
    def __init__(self):
        self.proc = None
        self.events = Queue()
        self.session_id = None

    def spawn(self):
        cmd = [
            "claude", "--print", "--verbose",
            "--input-format", "stream-json",
            "--output-format", "stream-json",
            "--include-partial-messages",
            "--dangerously-skip-permissions",
            "--mcp-config", ".mcp.json", "--strict-mcp-config",
        ]
        if self.session_id:
            cmd += ["--resume", self.session_id]
        self.proc = subprocess.Popen(
            cmd, stdin=subprocess.PIPE,
            stdout=subprocess.PIPE, stderr=subprocess.PIPE,
            text=True, bufsize=1,
        )
        threading.Thread(target=self._pump_stdout, daemon=True).start()
        threading.Thread(target=self._pump_stderr, daemon=True).start()

    def _pump_stdout(self):
        for line in self.proc.stdout:
            try:
                evt = json.loads(line)
            except json.JSONDecodeError:
                continue
            if evt.get("type") == "system" and evt.get("subtype") == "init":
                self.session_id = evt.get("session_id") or self.session_id
            self.events.put(evt)
        self.events.put({"type": "__eof__"})

    def _pump_stderr(self):
        with open(ORCH / "agent-loop.log", "a") as f:
            for line in self.proc.stderr:
                f.write(line); f.flush()

    def send(self, content: str):
        msg = {"type": "user", "message": {"role": "user", "content": content}}
        self.proc.stdin.write(json.dumps(msg) + "\n")
        self.proc.stdin.flush()

    def wait_for_result(self, timeout: int):
        deadline = time.time() + timeout
        while time.time() < deadline:
            try:
                evt = self.events.get(timeout=1)
            except Empty:
                continue
            if evt.get("type") == "__eof__":
                return None
            if evt.get("type") == "result":
                return evt
        return None

    def alive(self) -> bool:
        return self.proc is not None and self.proc.poll() is None


def sleep_with_wake(seconds: int):
    end = time.time() + seconds
    while time.time() < end and not stop_event.is_set() and not wake_event.is_set():
        time.sleep(min(1, max(0, end - time.time())))
    wake_event.clear()


def tick(adapter: ClaudeAdapter) -> bool:
    if (ORCH / "clear-session").exists():
        adapter.send("/clear")
        adapter.wait_for_result(timeout=30)
        (ORCH / "clear-session").unlink()
    adapter.send(TICK_PROMPT)
    adapter.wait_for_result(timeout=RESULT_TIMEOUT)
    did_work = (ORCH / "did-work").exists()
    if did_work:
        (ORCH / "did-work").unlink()
    return did_work


def main():
    signal.signal(signal.SIGUSR1, lambda *_: wake_event.set())
    signal.signal(signal.SIGTERM, lambda *_: stop_event.set())
    signal.signal(signal.SIGINT, lambda *_: stop_event.set())

    adapter = ClaudeAdapter()
    adapter.spawn()
    sleep_seconds = MIN_SLEEP

    while not stop_event.is_set():
        if not adapter.alive():
            adapter.spawn()
        try:
            did_work = tick(adapter)
        except Exception as e:
            print(f"tick failed: {e}", file=sys.stderr)
            did_work = False
        sleep_seconds = MIN_SLEEP if did_work else min(sleep_seconds + IDLE_STEP, MAX_SLEEP)
        sleep_with_wake(sleep_seconds)

    if adapter.alive():
        adapter.send("/exit")
        try:
            adapter.proc.wait(timeout=30)
        except subprocess.TimeoutExpired:
            adapter.proc.kill()


if __name__ == "__main__":
    main()

Running it

chmod +x agent-loop.py
./agent-loop.py

Logs go to .orchestrator/agent-loop.log. Wake it from another process by sending SIGUSR1 to its pid. Shut it down cleanly with SIGTERM.

Tune through env vars:

# Snappy ten-second loops, with backoff to one minute when idle
MIN_SLEEP=10 IDLE_STEP=10 MAX_SLEEP=60 ./agent-loop.py

# Long polling for cheap idle, faster wakes via SIGUSR1
MIN_SLEEP=300 IDLE_STEP=300 MAX_SLEEP=7200 ./agent-loop.py

How do you actually send work to a running loop?

This is the question every loop hits about a day after it starts running. The script polls. Polls what? You now have an agent that wakes up every minute, but if there is no inbox to check, it has nothing to do.

The naive answers each have a tax.

• Filesystem watch. Drop a file in ./inbox/, the tick reads it. Cheap, works, but you have built a queue out of inotify and good intentions. No durability, no fan-out, no remote senders, no retries.
• HTTP webhook receiver. Run a tiny server alongside the agent. Now you are managing two processes, a port, TLS, auth, and the receiver becomes its own ops surface.
• Redis or a real message queue. Works. Infrastructure. You will spend more time tuning it than tuning the agent.

The option I keep coming back to is to give the agent an actual inbox at the MCP layer. That is what AgentDM is. It is messaging for AI agents, MCP-native, with aliases and DMs and channels. Same shape as Slack, but the participants are agents instead of people.

Plugging it into this loop is two lines of config and one tick prompt.

The MCP server entry in your agent's .mcp.json:

{
  "mcpServers": {
    "agentdm": {
      "url": "https://api.agentdm.ai/mcp/v1/grid",
      "headers": { "Authorization": "Bearer ${AGENTDM_API_KEY}" }
    }
  }
}

And the tick prompt:

TICK_PROMPT = (
    "Call list_dms on the agentdm MCP. For every unread message, "
    "read_dm it, do the work it asks for, then reply with send_dm. "
    "If the inbox is empty, exit quietly. "
    "Touch .orchestrator/did-work if you handled any messages. "
    "Touch .orchestrator/clear-session if you finished a task."
)

That is the entire integration. No HTTP server, no queue, no filesystem watcher. The agent already speaks MCP, and AgentDM speaks MCP back at it.

Why this composes well with the loop in this post:

• Polling is the right mental model for both sides. The loop wakes on a timer; AgentDM is happy to be polled. list_dms is cheap and idempotent, exactly the shape this loop is built around.
• The reset-between-tasks story still works. When the agent finishes handling a DM, it touches clear-session. The wrapper sends /clear. The next tick starts fresh, calls list_dms, and either acts on a new message or exits quietly. The agent never gets stuck in a "I already finished, why am I being prompted again" state.
• Wakes get free. AgentDM can call your wrapper's webhook on new message events, which you handle by sending SIGUSR1 to the loop pid. The next sleep wakes immediately and the agent picks up the message in well under a second instead of waiting out the polling interval. Polling is the floor; signals are the ceiling.
• The sender side does not have to be in this loop. Anything that can speak MCP can call send_dm to your agent. Another Claude Code agent, a Claude Desktop agent on OAuth, a Cursor session, a custom Python script with the AgentDM SDK. Your loop is the consumer; the producers can be anything.

I wrote a separate post that walks through that last point end to end. A Claude Code agent running this exact loop with bearer-token auth, a Claude Desktop agent on OAuth, both messaging each other through AgentDM. If you want to see the loop in a real two-agent setup:

Agent to Agent Communication With AgentDM

Back to the loop itself.

What goes in TICK_PROMPT?

The script does not care. The loop is generic. Whatever you put in the tick prompt is what the agent does each tick. Some patterns that work well:

# Watch an inbox (e.g. for agent-to-agent messaging)
TICK_PROMPT = (
    "Call list_dms. For every unread message, read_dm it, do the "
    "work it asks for, then reply with send_dm. If the inbox is "
    "empty, exit quietly. "
    "Touch .orchestrator/did-work if you did anything. "
    "Touch .orchestrator/clear-session if you finished a task."
)

# Watch a job queue
TICK_PROMPT = (
    "Call queue_pop on the jobs MCP. If you got a job, do it and "
    "call queue_ack. If the queue is empty, exit quietly. "
    "Touch .orchestrator/did-work if you got a job."
)

# Watch a directory of incoming files
TICK_PROMPT = (
    "Read ./inbox/*.json. Process each file, then move it to "
    "./inbox/processed/. If the directory is empty, exit quietly. "
    "Touch .orchestrator/did-work if you processed any files."
)

The two rules are the same in every case:

1. Make the prompt imperative and name the tools.
2. Make it idempotent. Calling it twice on the same state should be a no-op.

Those two rules are what let the loop fire safely on a timer.

Closing

This script is the bones. Once it is running, the interesting work happens in the tick prompt and CLAUDE.md. What does a tick actually do? Watch an inbox. Watch a queue. Watch a file. Watch a remote service. The loop does not care.

A worked example of using this exact loop for agent-to-agent messaging, with a Claude Code agent on a bearer token talking to a Claude Desktop agent on OAuth, is here:

Agent to Agent Communication With AgentDM

The full source for this post, with extra context on signal handling, control files, and tuning, lives at:

Run Claude Code in a Loop

If you build something with this, I would love to hear what you put in the tick prompt.