ArgusBot is a Python supervision plugin for Codex CLI and Claude Code CLI. Its core purpose is to keep the agent running, reviewing, and planning until the task is truly complete, thereby solving the common "agent stops prematurely and asks for the next instruction" problem.
Main capabilities and how it works: the main agent executes tasks through the selected execution backend; the review sub-agent evaluates completion status (done / continue / blocked); the planning sub-agent maintains a real-time framework view and proposes the next session goal; the loop stops only when the reviewer indicates done and all acceptance checks pass. The default max_rounds is 500; the daemon sub-model inherits the default of the selected backend by default unless a preset or override is explicitly set; an idle run started by the daemon first attempts to resume from the last saved session_id.
Feature snapshot includes: the main agent's persistent loop with review gating; planning/management agent with real-time plan snapshots, workflow tables, and follow-up goal proposals; a planning TODO board (plan_todo.md) and explorer to-dos maintained across planning scans; a stall watchdog with soft diagnostics and a hard restart safety window; real-time visibility including terminal streaming, dashboard, Telegram push, and typing heartbeat; support for Telegram inbound control during runs (/inject, /status, /stop, voice/audio transcription); support for Feishu inbound control during runs (text polling and plain-text routing for /run, /inject, /status, /stop, /plan, /review); resident daemon mode for idle startup; daemon follow-up prompts; planning modes off, auto, record, with the default set to auto; daemon dual control channels Telegram and terminal; one-word operation entry argusbot; token-based unique daemon lock; operator message history persisted as markdown and fed back into review decisions; automatic generation of PPTX for run handoff; final handoff artifacts generated as Markdown and PPTX after the reviewer is done; run archives persisted as JSONL, including date/workspace/session metadata.
Quick start (24/7 Telegram control): you must first install and authenticate the selected backend CLI (make sure codex or claude is available, then run argusbot init).When running a 24/7 daemon, choosing high or xhigh reasoning may result in token usage close to running a Codex session continuously for 24 hours, so budget must be planned carefully; medium reasoning is usually the quality/cost compromise for long-running background control. Steps: clone the repository and install it in editable mode; enter the target project directory; run argusbot init, choose the control channel and execution backend, and complete the setup prompts; after setup, the daemon starts in the background and keeps running; use /run, /inject, /status, and /stop through a Telegram bot conversation to control it. During initialization, first choose the control channel (1. Telegram, 2. Feishu, suitable for the CN network environment), then choose the execution backend (1. Codex CLI, 2. Claude Code CLI), and then enter the credentials for the selected channel. Configuration is persisted under .argusbot/ in the main project.
Runtime backends: --runner-backend codex uses Codex CLI; --runner-backend claude uses Claude Code CLI; --runner-bin selects the underlying executable path, and --codex-bin serves as a compatibility alias. The Copilot proxy applies only to the Codex backend. Claude only accepts low|medium|high effort, so when Claude is selected, ArgusBot maps xhigh to high.
Why a plugin instead of a native flag: the current Codex CLI and Claude Code CLI do not provide a built-in --autoloop flag, so this repository adds a wrapper layer on top of their native task execution commands.
PPTX report dependency (optional): the PPTX run report generator uses a Node.js script; if node is unavailable, PPTX generation is silently skipped and does not block the loop.
Using GitHub Copilot through copilot-proxy: ArgusBot can route Codex backend calls to a local copilot-proxy checkout, so main/review/plan/BTW runs can use GitHub Copilot quota instead of OpenAI API billing. When enabled, it automatically starts proxy.mjs (if needed) andinjects a Codex provider override per run, without rewriting the global ~/.codex/config.toml. The Claude backend ignores Copilot proxy settings by design.
Native GitHub Copilot CLI backend: you can select backend 3. GitHub Copilot CLI from settings, or use the CLI directly. If the model setting is left blank, ArgusBot will not pass --model, and Copilot CLI keeps its official default model. --main-model, --reviewer-model, and --plan-model are forwarded to Copilot CLI --model when explicitly set; --main-reasoning-effort, --reviewer-reasoning-effort, and --plan-reasoning-effort map to Copilot CLI --reasoning-effort; --yolo maps to Copilot CLI --yolo / --allow-all. In non-interactive prompt mode, ArgusBot grants Copilot CLI automatic tool approval so runs can proceed autonomously; the native Copilot backend does not use copilot-proxy.
Single-word operation workflow (argusbot): on first run, it asks for the control channel (default Telegram), then selects the run backend (1. Codex CLI, 2. Claude Code CLI, 3. GitHub Copilot CLI), then collects credentials for the selected channel, writes .argusbot/daemon_config.json, and starts the daemon in the current shell directory. Subsequent runs reuse the configuration, ensure the daemon is running, and then attach directly to live output. argusbot init stops all current ArgusBot daemons, prompts for control channel + backend + credentials/model/play mode, starts the daemon in the background, and then exits. After init, running argusbot can attach the monitor to the background daemon.
The same terminal can control the daemon/run, with supported commands including /run <objective>, /new, /inject <instruction>, /mode <off|auto|record>, /btw <question>, /confirm-send, /cancel-send, /plan <session-goal-or-direction>, /review <criteria>, /show-main-prompt, /show-plan, /show-plan-context, /show-review [round], /show-review-context, /status, /stop, /daemon-stop. Plain text is automatically routed: running => inject, idle => run. Planning mode semantics: off disables the planning agent behavior for daemon-started runs; auto (default) keeps the planner enabled and it may propose the next request, but the daemon does not automatically run follow-ups until the current session goal is confirmed via /plan <session-goal>; record makes the planner only record markdown and not automatically execute follow-ups. Daemon-started runs always use --yolo by default.
Common options include --runner-backend {codex,claude,copilot}, --runner-bin <path>, --session-id <id>, --main-model / --reviewer-model, --planner-model, --copilot-proxy [--copilot-proxy-port 18080] [--copilot-proxy-dir /custom/path], python -m codex_autoloop.model_catalog, --yolo, --full-auto, --state-file <file>, --final-report-file <file>, --pptx-report-file <file>, --plan-report-file <file>, --plan-todo-file <file>, --plan-update-interval-seconds 1800, --verbose-events, --dashboard, --dashboard-host 0.0.0.0 --dashboard-port 8787,--telegram-bot-token + --telegram-chat-id, --telegram-events, --telegram-live-interval-seconds 30, --feishu-app-id / --feishu-app-secret / --feishu-chat-id, --feishu-events, --feishu-live-updates + --feishu-live-interval-seconds 30, --feishu-heartbeat-interval-seconds 600, --feishu-control, --no-live-terminal, --stall-soft-idle-seconds 3600, --stall-hard-idle-seconds 10800, --telegram-control, etc.
Important warning: daemon-started runs use --yolo by default, granting the selected backend high local execution privileges, and should only be run in trusted repositories/workspaces. Telegram/Feishu snippets may hide important details; if behavior is abnormal, first run argusbot in the target workspace to view local live output/logs. Long-running goals may consume a large number of tokens, and planner or reviewer quality may also cause repeated loops; you should always set clear acceptance checks, monitor runtime, and stop/re-scope when needed. The daemon supports remote control via Telegram and Feishu, and daemon-started runs may execute with high local privileges, so bot tokens, app secrets, and related credentials should be treated as highly sensitive; if credentials leak, unauthorized parties may issue remote commands that execute on your local machine or workspace; never share tokens, never commit them to repositories, and rotate immediately if exposure is suspected.
