AgentCruise

🚀 Autopilot for AI coding agents — put Claude Code / OpenAI Codex / Gemini CLI on "cruise control" and loop tasks unattended.

✨ Features

• 🤖 Multi-agent support — one tool drives claude / codex / gemini, auto-detecting each and injecting its own no-confirmation flags
• 🔄 Automatic loops — run the same command any number of times
• ⏱️ Inter-command delay — configurable wait time between commands
• 📊 Visual progress bar — live progress and estimated time remaining
• 🎯 Smart completion detection — soft/hard dual timeout: after silence exceeds the soft timeout, if the screen still shows a busy indicator (e.g. codex's esc to interrupt during a reasoning stream) it keeps waiting, so a "busy but quiet" sub-agent isn't mistaken for idle and sent the next command or restarted prematurely
• 🏁 Sentinel-based round completion — --until <sentinel>: when the agent prints the agreed sentinel on its own line, the round is marked done and the next one starts immediately — faster and more accurate than pure silence timeout
• 🚪 Exit when done — --exit-on-done: cleanly exit after all rounds finish, no need to sit on Ctrl+C
• 🛡️ Unattended — automatically handles permission prompts and interactive menus; restarts on disconnect/idle
• 🎛️ Runtime hotkey tuning — press Ctrl+O while running to open a config panel and change loops / delay / timeout / command / launcher / clear / restart mid-run; ordinary changes take effect on the next round, while changing the launcher (for example cx → cxh) automatically restarts the agent process
• 🕐 Scheduled windows — run only within a given time window (e.g. overnight)
• ✅ Conditional execution — run only when a condition is met (e.g. sufficient credits)
• 🌐 Proxy support — specify a proxy server
• 🌈 Colored logging — clear, color-coded status output

🤖 Supported Agents

| Command | Aliases | Auto-injected flags | Clear command | |---------|---------|---------------------|---------------| | claude | cld ccd ccr | --dangerously-skip-permissions | /clear | | codex | cx | --dangerously-bypass-approvals-and-sandbox | /new | | gemini | gm | --yolo | /clear |

📦 Installation

Global (npm)

npm install -g agentcruise

From source

npm install       # local install
npm install -g .  # global install from source

After installing you can use agentcruise or the short alias cruise.

🚀 Usage

Basics

# Run once (defaults to claude)
agentcruise "ls -la"

# Use codex / gemini
agentcruise codex "ls -la"
agentcruise gemini "ls -la"

# Run multiple times
agentcruise "ls -la" --loops 5

# Set the delay between commands
cruise "ls -la" --loops 5 --delay 3

Options

agentcruise [<agent-command>] <command-to-run> [options]

Positional arguments:
  agent-command        Command that launches the AI agent (default: claude; also codex / gemini)
  command-to-run       Command to execute inside the agent

Options:
  --loops, -l <n>      Number of runs (default: 1)
  --delay, -d <sec>    Delay between commands (default: 1s)
  --timeout, -t <sec>  Command execution timeout (default: 30s)
  --proxy, -p <addr>   Proxy server, e.g. 127.0.0.1:7897 (default: none)
  --command, -c <cmd>  Command to execute (option form)
  --clear              Clear before each command (claude: /clear, codex: /new)
  --restart            Fully stop and restart the agent process after each command
  --time <window>      Run only within a time window, e.g. 1:00-13:00 (24-hour)
  --condition <type>   Execution condition check, e.g. aiwithcode (credits > 4000)
  --until <sentinel>   When the agent prints this string on its own line, mark the round
                       done and move on (a note is auto-appended each round telling the
                       agent to emit the sentinel)
  --exit-on-done       Cleanly exit (exit 0) after all rounds finish instead of waiting on Ctrl+C

Examples

# Basic
agentcruise "echo hello"

# Run codex 10 times, 2s apart
agentcruise codex "date" --loops 10 --delay 2

# Short flags
cruise "pwd" -l 3 -d 5

# Full option form
agentcruise --command "ls -la" --loops 5 --delay 3

# Clear conversation history before each command
agentcruise "echo test" --clear -l 10

# Restart the process after each command
agentcruise "echo test" --restart -l 10

# Only run between 1:00 and 13:00
agentcruise "echo hello" --time 1:00-13:00

# Only run when credits are sufficient
agentcruise "echo hello" --condition aiwithcode -l 10

# Use a proxy server
agentcruise "echo hello" --proxy 127.0.0.1:7897

# Combined: custom agent + proxy + multiple runs
agentcruise codex "ls -la" --proxy 127.0.0.1:7897 --loops 5 --delay 2

📊 Progress Bar

When running multiple times (loops > 1), a progress bar is shown:

┌─────────────────────────────────────────────────────────────────────────────┐
│ Progress: [████████████░░░░░░░░] 60% (3/5)  │ Since last activity: 15s        │
│ Current command: ls -la                     │ Est. remaining: 2m30s           │
└─────────────────────────────────────────────────────────────────────────────┘

• 📈 Live progress — current progress and percentage
• ⏰ Activity monitor — time since the agent's last activity
• 🔮 Time estimate — smart estimate of remaining time from elapsed runs
• 🎨 Clean UI — Unicode box-drawing borders

🛠️ How It Works

1. Identify the agent — detect claude / codex / gemini from the command and inject the matching no-confirmation flags
2. Launch the process — start the AI agent inside a pseudo-terminal (pty)
3. Handle permissions — automatically deal with permission prompts and interactive menu selections
4. Send the command — use multiple methods to make sure the command is delivered
5. Completion detection (soft/hard dual timeout) — after no output for the soft timeout (-t, default 30s), first check whether the bottom of the screen still shows a busy indicator (esc to interrupt): if still busy, keep waiting until the hard timeout backstop. This avoids mistaking an agent that is quietly waiting on a reasoning stream (e.g. codex) for idle
6. Self-healing loop — on idle/disconnect/context-overflow, automatically clear or restart, then run the next round after the configured delay

⏱️ About Timeouts

• -t, --timeout <sec>: the soft timeout, the silence threshold for "possibly done" (default 30s).
• Hard timeout: after the soft timeout, if the screen still looks busy it waits up to the hard timeout. Default is max(soft × 6, 180s), overridable via env var:

  AGENTCRUISE_HARD_TIMEOUT_SEC=300 agentcruise codex "..." -t 30

• Debug event log: set AGENTCRUISE_EVENT_LOG=<path> to write lifecycle events as JSON Lines — ready/command_sent/idle_complete/idle_but_busy/restart/all_done, sentinel-based round_done, and config-panel config_open/config_set/config_close — handy for troubleshooting and automated tests (see test/).

🏁 Sentinel-based Round Completion (--until)

By default a round is considered done via silence timeout (plus the busy indicator) — you have to wait until the agent has been quiet long enough. --until is faster and more precise: the agent emits an agreed sentinel on its own line when each round's task is done, and the moment AgentCruise detects that line it marks the round complete and moves to the next one, with no idle waiting.

# Loop 20 rounds; each round advances once the agent prints <promise>DONE</promise>
agentcruise "continue implementing the next TODO item" -l 20 --until "<promise>DONE</promise>"

• No need to write the sentinel instruction yourself: with --until enabled, AgentCruise auto-appends a note at the end of each round's command telling the agent to print the sentinel on its own line when done. (If your command already contains the sentinel string, it's assumed you provided the instruction and nothing extra is injected.)
• Only counts a sentinel the agent actually emits on its own line: the sentinel inside the injected note is quoted and embedded mid-sentence, so it doesn't occupy a line by itself when the command is echoed — command echo is never mistaken for completion. Only the bare sentinel the agent prints on a fresh line counts.
• Detection runs line-by-line on the ANSI-stripped scrollback (so color codes don't split the sentinel), and the buffer is cleared each round (so a previous round's sentinel can't bleed over).
• A match writes a round_done{reason:"until"} event to the log for automation.

🎛️ Runtime Config Panel (Ctrl+O)

During long unattended runs you often want to tweak a parameter mid-run without interrupting the current turn. Press Ctrl+O anytime to open the config panel (rendered on the terminal's alternate screen; the agent keeps running in the background and its display is restored exactly on exit):

 AgentCruise · Runtime parameters  (Claude)
 ────────────────────────────────────
 ▶ loops        2 left / 20 total
   delay        5 s
   timeout(soft) 30 s
   timeout(hard) 180 s
   command      "continue with the next todo"
   clear        ● on
   restart      ○ off
   background   浅灰 light  (1/6)
 ────────────────────────────────────
 背景预览:
  AgentCruise  Claude ▕██████░░░░░░▏ 50% 1/2  示例消息 sample text   00:12:34 · idle 5s · ↑ ...
 ────────────────────────────────────
 ↑↓ select   Enter edit/toggle   q save & back   Esc cancel

• ↑↓ (or k/j) to select a field, Enter to edit a numeric/text field or toggle a boolean, q to save and return, Esc to cancel.
• loops accepts an absolute value (e.g. 30) or a relative change (+5 / -2); it can't be set below the number of runs already completed.
• background cycles the bottom status-bar color theme (Enter to switch); a live preview of the bar is shown right below the fields. Six themes ship — light (default), paper, sky, mint, rose, dark — all light-background except dark.
• All changes take effect on the next round, no process restart.
• The panel is only available on an interactive TTY; in non-TTY runs (pipe/background) the hotkey is automatically disabled.

Set the default theme without opening the panel via env var:

AGENTCRUISE_BAR_THEME=paper agentcruise "..." -l 20

🛰️ Central Control (optional)

An AgentCruise instance still runs fully standalone. Optionally, it can also report its status to a central hub and be controlled remotely — so one dashboard (or any script) can watch every instance's progress and history, and push commands/control to any of them.

The hub is a plain service; the web page is just an optional shell on top of it — any WebSocket client speaks the same protocol, and a REST snapshot is exposed at /api/agents.

Start the hub:

agentcruise serve                       # binds 127.0.0.1:8787 by default
agentcruise serve --port 9000 --no-web  # custom port, disable the web shell

Point an instance at it (per-run flag, env var, or config file):

agentcruise codex "继续做任务" -l 50 --server ws://127.0.0.1:8787 --name box-A

• The instance dials out to the hub over WebSocket, so it works behind NAT/inside a private network — the hub only needs one inbound port.
• The link is a pure side-channel: if the hub is down or the connection drops, the instance keeps looping and silently auto-reconnects. Standalone reliability always comes first.
• It reports: current loop x/y, state, idle/uptime, current command, structured lifecycle events, and a rolling ANSI-stripped output tail.
• It accepts, over the same link: command (send = inject into the agent now) and control — every field of the Ctrl+O panel (loops / delay / soft & hard timeout / looped command / launcher / clear / restart / theme) is editable per instance right from the dashboard. Launcher changes restart that agent automatically; other changes apply live (next round).
• The dashboard renders each instance's terminal with xterm.js (faithful ANSI/TUI, colors), and keeps a per-round history you can page through with a dropdown (实时 / 第 k 轮). View modes: grid / rows, plus a per-card maximize (⤢). Choices persist in localStorage.
• Login: the dashboard is password-protected. On first visit you set a password (sha256 stored in the config file); afterwards you log in. Pass --password <pw> to set it without persisting, or --no-auth to disable (e.g. tests). Agent dial-in (/agent) is not gated; the dashboard and control/launch are.
• Launch from the UI: the ＋ 新建 button starts a new instance — pick a directory, launcher (cxh / cch / codex / …), task and loops; the hub spawns agentcruise there and it dials back in. (This is effectively remote execution, hence gated behind login.)
• First release is localhost, in-memory (state resets when the hub restarts).

Endpoints: ws://host:port/agent (instances), ws://host:port/dashboard (dashboards), GET /api/agents (JSON snapshot), GET / (web shell).

⚙️ Config File

Long-lived settings live in ~/.agentcruise/config.json (e.g. hub URL, default theme, instance name):

{
  "server": { "url": "ws://127.0.0.1:8787", "enabled": true },
  "theme": "paper",
  "name": "box-A"
}

Resolution order (highest wins): CLI flag > environment variable > config file > built-in default.

📋 Requirements

• Node.js >= 18 (works on 18 / 20 / 22 / 24 — the native PTY ships prebuilt binaries, so no compiler or specific Node version is required)
• The corresponding AI agent CLI installed (Claude Code / Codex / Gemini)
• An environment that supports pseudo-terminals

🔧 Dependencies

• @homebridge/node-pty-prebuilt-multiarch — pseudo-terminal support with prebuilt binaries across Node versions and platforms (no build toolchain needed)
• ws / playwright — helpers for condition checks and related features

📝 Development

# Clone
git clone https://github.com/fuzihaofzh/agentcruise.git
cd agentcruise

# Install dependencies
npm install

# Local test
./index.js "echo test" --loops 3

🤝 Contributing

Issues and Pull Requests are welcome!

📄 License

MIT License

🤖 Generated with Claude Code