ArgusBot

Docs: Quick Start | Recent Updates | Contributing

What's New: See Recent Updates for the latest user-visible changes.

ArgusBot is a Python supervisor plugin for Codex CLI and Claude Code CLI:

• Main agent executes the task through the selected runner backend
• Reviewer sub-agent evaluates completion (done / continue / blocked)
• Planner sub-agent maintains a live framework view and proposes next-session objectives
• Loop only stops when reviewer says done and all acceptance checks pass

This solves the common "agent stopped early and asked for next instruction" problem.

Current defaults:

• max_rounds defaults to 500.
• Daemon child model defaults now inherit the selected backend's defaults unless you explicitly set a preset/override.
• Daemon-launched idle runs try to resume from the last saved session_id before starting a fresh thread.

Important Warnings

1. Security risk: daemon-launched runs use --yolo by default. This grants the selected backend high local execution power. Run only in trusted repositories/workspaces.
2. Visibility and debugging: Telegram/Feishu snippets may hide important details. If behavior looks wrong, run argusbot in the target workspace and watch local live output/logs first.
3. Cost and loop risk: long-running objectives can consume significant tokens. Planner or reviewer quality can also cause repeated loops. Always set clear acceptance checks, monitor runtime, and stop/re-scope when needed.
4. Credential and remote-control security: ArgusBot supports daemonized remote control through channels such as Telegram and Feishu, while daemon-launched runs may execute with high local privileges. Treat bot tokens, app secrets, and related credentials as highly sensitive. If these credentials are leaked, an unauthorized party may be able to issue remote commands that execute on your local machine or workspace. Never share tokens, never commit them to a repository, and rotate them immediately if exposure is suspected.

Community

If you're using ArgusBot for research workflows, welcome to join our user community.

• WeChat user group: scan the QR code below
• Please note your background / use case when joining

<p align="center"> <img src="Feishu_readme/wechat-group.jpg" alt="ArgusBot WeChat Group" width="260" /> </p>

Quick Start (24/7 Telegram Control)

If you want to control your main project from Telegram 24/7 with an always-on daemon, use this flow:

Prerequisites and cost notes:

• You must have your chosen backend CLI installed and authenticated first (make sure codex or claude works before running argusbot init).
• For 24/7 daemon operation, choosing high or xhigh reasoning can lead to token usage close to running one Codex session continuously for 24 hours. Plan budget carefully.
• medium reasoning is usually a good quality/cost tradeoff for long-running background control.

1. Clone this repo and install it in editable mode.
2. Go to your target project directory (the repo you actually want to operate on).
3. Run argusbot init, choose control channel and execution backend, then complete setup prompts.
4. After setup, daemon starts in background and keeps running.
5. Chat with your Telegram bot (/run, /inject, /status, /stop) to control work at any time.

Example:

# 1) clone + install ArgusBot
git clone <your-ArgusBot-repo-url> ArgusBot
cd ArgusBot
python -m pip install -e .

# 2) go to your main project
cd ..
cd <your_main_project>

# 3) initialize daemon config in this project
argusbot init

During argusbot init, first choose control channel (1. Telegram, 2. Feishu (适合CN网络环境)), then choose execution backend (1. Codex CLI, 2. Claude Code CLI), then enter the selected channel credentials. Config is persisted under .argusbot/ in your main project.

Current Feature Snapshot

• Persistent main-agent loop with reviewer gating (done/continue/blocked).
• Planner/manager agent with live plan snapshots, workstream table, and follow-up objective proposal.
• Planner TODO board (plan_todo.md) and explorer backlog maintained across planning sweeps.
• Stall watchdog with soft diagnosis and hard restart safety window.
• Live visibility: terminal streaming, dashboard, Telegram push, typing heartbeat.
• Telegram inbound control during active run: /inject, /status, /stop, voice/audio transcription.
• Feishu inbound control during active run: text polling for /run, /inject, /status, /stop, /plan, /review, and plain-text routing.
• Always-on daemon mode for idle startup: /run can launch new runs when no loop is active.
• Daemon follow-up prompt: after a run ends, Telegram can offer the planner's next suggested objective as a one-click continuation, but auto follow-up stays locked until /plan <session-goal> confirms the current session goal.
• Planner modes: off, auto, record; setup defaults to auto, while daemon follow-up stays execute-only until /plan confirms the session goal.
• Dual control channels for daemon: Telegram and terminal (argusbot-daemon-ctl).
• Single-word operator entrypoint: argusbot (first run setup, later auto-attach monitor).
• Token-exclusive daemon lock: one active daemon per Telegram token.
• Operator message history persisted to markdown and fed to reviewer decisions.
• PPTX auto-generation for run handoff: builds a presentation-ready slide deck summarizing the completed work.
• Interactive PPTX opt-in: when running argusbot-run interactively, the CLI asks whether to generate a PPTX report before starting. Answer Y (default) to enable or n to skip. Daemon-launched runs (Telegram/Feishu) also ask via the control channel before each /run launch — reply Y or N to confirm. Use --pptx-report / --no-pptx-report to bypass the prompt.
• Final handoff artifacts generated after reviewer done: Markdown via --final-report-file and PPTX via --pptx-report-file, with notifier delivery when ready.
• Run archive persisted as JSONL with date/workspace/session metadata for resume continuity.
• Utility scripts: start/kill/watch daemon logs, plus sanitized cross-project setup examples.

Runner Backends

ArgusBot keeps the same /run, /inject, /btw, planner, reviewer, and daemon flows across both backends.

• --runner-backend codex uses Codex CLI.
• --runner-backend claude uses Claude Code CLI.
• --runner-bin selects the underlying executable path; --codex-bin remains as a compatibility alias.
• Copilot proxy applies only to the Codex backend.
• Claude accepts low|medium|high effort only, so ArgusBot maps xhigh -> high when Claude is selected.

Why this is a plugin, not a native flag

Current Codex CLI and Claude Code CLI do not expose a built-in --autoloop flag, so this repo adds a wrapper layer around their native task execution commands.

Install

python -m venv .venv
source .venv/bin/activate
pip install -e .

PPTX Report Dependencies (optional)

The PPTX run report generator uses a Node.js script. To enable it:

npm install   # installs pptxgenjs and other JS dependencies

If node is not available, PPTX generation is silently skipped and does not block the loop.

GitHub Copilot via copilot-proxy

ArgusBot can route Codex backend calls through a local copilot-proxy checkout, so main/reviewer/planner/BTW runs can use GitHub Copilot-backed quota instead of OpenAI API billing.

Simplest setup:

argusbot init

During argusbot init / argusbot-setup, ArgusBot will:

• auto-detect an existing proxy checkout in ~/copilot-proxy, ~/copilot-codex-proxy, or ~/.argusbot/tools/copilot-proxy
• if you select the copilot preset (or explicitly enable Copilot proxy), offer to auto-install the proxy into ~/.argusbot/tools/copilot-proxy

Direct CLI example:

argusbot-run \
  --copilot-proxy \
  --main-model gpt-5.4 \
  --reviewer-model gpt-5.4 \
  --plan-model gpt-5.4 \
  "实现功能并跑完验证"

Notes:

• --copilot-proxy-dir is only needed when your proxy checkout lives outside the auto-detected locations above.
• When enabled, ArgusBot auto-starts proxy.mjs if needed and injects Codex provider overrides per run, so you do not have to rewrite your global ~/.codex/config.toml.
• Claude backend ignores Copilot proxy settings by design.
• Prefer Copilot-supported models such as gpt-5.4, gpt-5.2, gpt-5.1, gpt-4o, claude-sonnet-4.6, claude-opus-4.6, or gemini-3-pro-preview.

Native GitHub Copilot CLI backend

ArgusBot also supports GitHub Copilot CLI as a native execution backend, separate from the copilot-proxy flow above.

Use it from setup:

• argusbot init
• choose backend 3. GitHub Copilot CLI

Or directly from CLI:

argusbot-run \
  --runner-backend copilot \
  "实现功能并完成验证"

Notes:

• If you leave model settings empty, ArgusBot does not pass --model, so Copilot CLI keeps its own official default model.
• --main-model, --reviewer-model, and --plan-model are forwarded to Copilot CLI --model when you explicitly set them.
• --main-reasoning-effort, --reviewer-reasoning-effort, and --plan-reasoning-effort map to Copilot CLI --reasoning-effort.
• --yolo maps to Copilot CLI --yolo / --allow-all for highest-permission runs.
• In non-interactive prompt mode, ArgusBot grants Copilot CLI tool auto-approval so the run can proceed autonomously; native Copilot backend does not use copilot-proxy.

One-word operator workflow (argusbot)

Run:

argusbot

List support