Skip to content
Back to search

ArgusBot

ArgusBot: A 24/7 supervisor Agent for Codex CLI and Claude Code CLI that keeps agents running, reviewing, and planning until the job is actually done.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/waltstephen--argusbot/badge.svg)](/listings/waltstephen--argusbot)

HTML

<a href="/listings/waltstephen--argusbot"><img src="/api/listings/waltstephen--argusbot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 751 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ArgusBot
  2. ![ArgusBot banner](Feishu_readme/cleaned_Gemini_Generated_Image_2ji5ho2ji5ho2ji5.png)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  4. [![Contributing](https://img.shields.io/badge/Contributing-Guide-blue.svg)](CONTRIBUTING.md)
  5. Docs: [Quick Start](QUICKSTART.md) | [Recent Updates](WHATS_NEW.md) | [Contributing](CONTRIBUTING.md)
  6. > What's New: See [Recent Updates](WHATS_NEW.md) for the latest user-visible changes. (Sorry, we've been too busy lately, we'll be updating again in May.)
  7. `ArgusBot` is a Python supervisor plugin for Codex CLI and Claude Code CLI:
  8. - Main agent executes the task through the selected runner backend
  9. - Reviewer sub-agent evaluates completion (`done` / `continue` / `blocked`)
  10. - Planner sub-agent maintains a live framework view and proposes next-session objectives
  11. - Loop only stops when reviewer says `done` and all acceptance checks pass
  12. This solves the common "agent stopped early and asked for next instruction" problem.
  13. Current defaults:
  14. - `max_rounds` defaults to `500`.
  15. - Daemon child model defaults now inherit the selected backend's defaults unless you explicitly set a preset/override.
  16. - Daemon-launched idle runs try to resume from the last saved `session_id` before starting a fresh thread.
  17. ## Important Warnings
  18. 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.
  19. 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.
  20. 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.
  21. 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.
  22. ![ArgusBot architecture concept](Feishu_readme/cleaned_Gemini_Generated_Image_xniz1sxniz1sxniz%20(1).png)
  23. ## Community
  24. If you're using ArgusBot for research workflows, welcome to join our user community.
  25. - WeChat user group: scan the QR code below
  26. - Please note your background / use case when joining
  27. <p align="center">
  28. <img src="Feishu_readme/wechat-group.jpg" alt="ArgusBot WeChat Group" width="260" />
  29. </p>
  30. ## Quick Start (24/7 Telegram Control)
  31. If you want to control your main project from Telegram 24/7 with an always-on daemon, use this flow:
  32. Prerequisites and cost notes:
  33. - You must have your chosen backend CLI installed and authenticated first (make sure `codex` or `claude` works before running `argusbot init`).
  34. - 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.
  35. - `medium` reasoning is usually a good quality/cost tradeoff for long-running background control.
  36. 1. Clone this repo and install it in editable mode.
  37. 2. Go to your target project directory (the repo you actually want to operate on).
  38. 3. Run `argusbot init`, choose control channel and execution backend, then complete setup prompts.
  39. 4. After setup, daemon starts in background and keeps running.
  40. 5. Chat with your Telegram bot (`/run`, `/inject`, `/status`, `/stop`) to control work at any time.
  41. Example:
  42. ```bash
  43. # 1) clone + install ArgusBot
  44. git clone <your-ArgusBot-repo-url> ArgusBot
  45. cd ArgusBot
  46. python -m pip install -e .
  47. # 2) go to your main project
  48. cd ..
  49. cd <your_main_project>
  50. # 3) initialize daemon config in this project
  51. argusbot init
  52. ```
  53. 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.
  54. ## Current Feature Snapshot
  55. - Persistent main-agent loop with reviewer gating (`done/continue/blocked`).
  56. - Planner/manager agent with live plan snapshots, workstream table, and follow-up objective proposal.
  57. - Planner TODO board (`plan_todo.md`) and explorer backlog maintained across planning sweeps.
  58. - Stall watchdog with soft diagnosis and hard restart safety window.
  59. - Live visibility: terminal streaming, dashboard, Telegram push, typing heartbeat.
  60. - Telegram inbound control during active run: `/inject`, `/status`, `/stop`, voice/audio transcription.
  61. - Feishu inbound control during active run: text polling for `/run`, `/inject`, `/status`, `/stop`, `/plan`, `/review`, and plain-text routing.
  62. - Always-on daemon mode for idle startup: `/run` can launch new runs when no loop is active.
  63. - 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.
  64. - Planner modes: `off`, `auto`, `record`; setup defaults to `auto`, while daemon follow-up stays `execute-only` until `/plan` confirms the session goal.
  65. - Dual control channels for daemon: Telegram and terminal (`argusbot-daemon-ctl`).
  66. - Single-word operator entrypoint: `argusbot` (first run setup, later auto-attach monitor).
  67. - Token-exclusive daemon lock: one active daemon per Telegram token.
  68. - Operator message history persisted to markdown and fed to reviewer decisions.
  69. - PPTX auto-generation for run handoff: builds a presentation-ready slide deck summarizing the completed work.
  70. - 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.
  71. - Final handoff artifacts generated after reviewer `done`: Markdown via `--final-report-file` and PPTX via `--pptx-report-file`, with notifier delivery when ready.
  72. - Run archive persisted as JSONL with date/workspace/session metadata for resume continuity.
  73. - Utility scripts: start/kill/watch daemon logs, plus sanitized cross-project setup examples.
  74. ## Runner Backends
  75. ArgusBot keeps the same `/run`, `/inject`, `/btw`, planner, reviewer, and daemon flows across both backends.
  76. - `--runner-backend codex` uses Codex CLI.
  77. - `--runner-backend claude` uses Claude Code CLI.
  78. - `--runner-bin` selects the underlying executable path; `--codex-bin` remains as a compatibility alias.
  79. - Copilot proxy applies only to the Codex backend.
  80. - Claude accepts `low|medium|high` effort only, so ArgusBot maps `xhigh -> high` when Claude is selected.
  81. ## Why this is a plugin, not a native flag
  82. 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.
  83. ## Install
  84. ```bash
  85. python -m venv .venv
  86. source .venv/bin/activate
  87. pip install -e .
  88. ```
  89. ### PPTX Report Dependencies (optional)
  90. The PPTX run report generator uses a Node.js script. To enable it:
  91. ```bash
  92. npm install # installs pptxgenjs and other JS dependencies
  93. ```
  94. If `node` is not available, PPTX generation is silently skipped and does not block the loop.
  95. ## GitHub Copilot via `copilot-proxy`
  96. 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.
  97. Simplest setup:
  98. ```bash
  99. argusbot init
  100. ```
  101. During `argusbot init` / `argusbot-setup`, ArgusBot will:
  102. - auto-detect an existing proxy checkout in `~/copilot-proxy`, `~/copilot-codex-proxy`, or `~/.argusbot/tools/copilot-proxy`
  103. - if you select the `copilot` preset (or explicitly enable Copilot proxy), offer to auto-install the proxy into `~/.argusbot/tools/copilot-proxy`
  104. Direct CLI example:
  105. ```bash
  106. argusbot-run \
  107. --copilot-proxy \
  108. --main-model gpt-5.4 \
  109. --reviewer-model gpt-5.4 \
  110. --plan-model gpt-5.4 \
  111. "实现功能并跑完验证"
  112. ```
  113. Notes:
  114. - `--copilot-proxy-dir` is only needed when your proxy checkout lives outside the auto-detected locations above.
  115. - 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`.
  116. - Claude backend ignores Copilot proxy settings by design.
  117. - 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`.
  118. ## Native GitHub Copilot CLI backend
  119. ArgusBot also supports GitHub Copilot CLI as a native execution backend, separate from the `copilot-proxy` flow above.
  120. Use it from setup:
  121. - `argusbot init`
  122. - choose backend `3. GitHub Copilot CLI`
  123. Or directly from CLI:
  124. ```bash
  125. argusbot-run \
  126. --runner-backend copilot \
  127. "实现功能并完成验证"
  128. ```
  129. Notes:
  130. - If you leave model settings empty, ArgusBot does not pass `--model`, so Copilot CLI keeps its own official default model.
  131. - `--main-model`, `--reviewer-model`, and `--plan-model` are forwarded to Copilot CLI `--model` when you explicitly set them.
  132. - `--main-reasoning-effort`, `--reviewer-reasoning-effort`, and `--plan-reasoning-effort` map to Copilot CLI `--reasoning-effort`.
  133. - `--yolo` maps to Copilot CLI `--yolo` / `--allow-all` for highest-permission runs.
  134. - 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`.
  135. ## One-word operator workflow (`argusbot`)
  136. Run:
  137. ```bash
  138. argusbot
  139. ```
  140. List supported features/commands:
  141. ```bash
  142. argusbot help
  143. ```
  144. Behavior:
  145. - First run: asks you to choose control channel (`1. Telegram`, `2. Feishu (适合CN网络环境)`, default Telegram), then choose runner backend (`1. Codex CLI`, `2. Claude Code CLI`, `3. GitHub Copilot CLI`), then collects selected channel credentials, writes `.argusbot/daemon_config.json`, and starts daemon in the current shell directory.
  146. - Later runs: reuses config, ensures daemon is running, then directly attaches to live output.
  147. - `argusbot init`: stops all current ArgusBot daemons, prompts control channel + backend + credentials/model/play mode, starts daemon in background, then exits.
  148. - After `init`, run `argusbot` to attach monitor to that background daemon.
  149. - Same terminal can control daemon/run:
  150. - `/run <objective>`
  151. - `/new`
  152. - `/inject <instruction>`
  153. - `/mode <off|auto|record>`
  154. - `/btw <question>`
  155. - `/confirm-send` (when BTW attachments > 5, confirm and continue upload)
  156. - `/cancel-send` (when BTW attachments > 5, skip upload)
  157. - BTW attachment return supports Telegram/Feishu media upload: images/photos, videos, and generic files/documents.
  158. - `/plan <session-goal-or-direction>` (confirm the current session-level goal for planning; required before auto follow-up)
  159. - `/review <criteria>`
  160. - `/show-main-prompt`
  161. - `/show-plan`
  162. - `/show-plan-context`
  163. - `/show-review [round]`
  164. - `/show-review-context`
  165. - `/status`, `/stop`, `/daemon-stop`
  166. - plain text auto-routes: running => inject, idle => run
  167. Planner mode semantics:
  168. - `off`: disable plan agent behavior for daemon-launched runs.
  169. - `auto` (default): planner stays enabled and may propose the next request, but daemon does not auto-run follow-up until `/plan <session-goal>` confirms the current session goal.
  170. - `record`: planner records markdown only; no automatic follow-up execution.
  171. YOLO policy:
  172. - Daemon-launched runs always use `--yolo` by default.
  173. Directly disable daemon from terminal:
  174. ```bash
  175. argusbot daemon-stop
  176. ```
  177. You can still use low-level commands when needed:
  178. ```bash
  179. argusbot-daemon-ctl --bus-dir .argusbot/bus status
  180. argusbot-daemon-ctl --bus-dir .argusbot/bus inject "先修测试再继续"
  181. ```
  182. ## Run
  183. ```bash
  184. argusbot-run \
  185. --max-rounds 10 \
  186. --check "pytest -q" \
  187. "Implement feature X and keep iterating until tests pass"
  188. ```
  189. Report artifact example:
  190. ```bash
  191. argusbot-run \
  192. --state-file .argusbot/state.json \
  193. --final-report-file .argusbot/review_summaries/final-task-report.md \
  194. --pptx-report-file .argusbot/run-report.pptx \
  195. "实现功能并同时产出 Markdown 与 PPTX 汇报"
  196. ```
  197. This keeps both handoff artifacts in predictable paths. The PPTX report is also the file pushed by Telegram/Feishu when the run emits `pptx.report.ready`.
  198. Release note: if `--pptx-report-file` is not passed, ArgusBot still resolves a default PPTX artifact path under the run artifact directory using the standard file name `run-report.pptx`.
  199. Common options:
  200. - `--runner-backend {codex,claude,copilot}`: select the execution backend
  201. - `--runner-bin <path>`: select the backend executable path
  202. - `--session-id <id>`: continue an existing runner session
  203. - `--main-model` / `--reviewer-model`: set model(s)
  204. - `--planner-model`: override the manager/planner model (defaults to reviewer settings when omitted)
  205. - `--copilot-proxy [--copilot-proxy-port 18080] [--copilot-proxy-dir /custom/path]`: route Codex backend through local `copilot-proxy`
  206. - `python -m codex_autoloop.model_catalog`: list common models and presets
  207. - `--yolo`: request the selected backend's highest-permission autonomous mode
  208. - `--full-auto`: request automatic tool approval mode when supported by the selected backend
  209. - `--state-file <file>`: write round-by-round state JSON
  210. - `--final-report-file <file>`: write the final handoff Markdown report after reviewer `done`
  211. - `--pptx-report-file <file>`: write the auto-generated PPTX run report (default artifact name: `run-report.pptx`)
  212. - `--plan-report-file <file>`: write the latest planner markdown snapshot
  213. - `--plan-todo-file <file>`: write the latest planner TODO board markdown
  214. - `--plan-update-interval-seconds 1800`: run background planning sweeps every 30 minutes
  215. - `--verbose-events`: print raw JSONL stream
  216. - `--dashboard`: launch a live local web dashboard
  217. - `--dashboard-host 0.0.0.0 --dashboard-port 8787`: expose dashboard to other devices in LAN
  218. - `--telegram-bot-token` + `--telegram-chat-id`: send progress to Telegram (recommended for cross-network access)
  219. - `--telegram-events`: choose which events are pushed (comma-separated)
  220. - `--telegram-live-interval-seconds 30`: push live agent message deltas every 30s (only when changed)
  221. - `--feishu-app-id` / `--feishu-app-secret` / `--feishu-chat-id`: enable Feishu notifications and control
  222. - `--feishu-events`: choose which events are pushed to Feishu (comma-separated)
  223. - `--feishu-live-updates` + `--feishu-live-interval-seconds 30`: push live agent message deltas to Feishu (only when changed)
  224. - `--feishu-heartbeat-interval-seconds 600`: when a run is still active, send a Feishu heartbeat (`typing...`) every 10 minutes
  225. - `--feishu-control`: allow Feishu inbound control (`/inject`, `/status`, `/stop`, `/plan`, `/review`) while loop is running
  226. - `--no-live-terminal`: disable realtime terminal prints (default is on)
  227. - `--stall-soft-idle-seconds 3600`: after 1h no new output, run stall sub-agent diagnosis (do not force kill)
  228. - `--stall-hard-idle-seconds 10800`: after 3h no new output, force restart as hard safety valve
  229. - `--telegram-control`: allow Telegram inbound control (`/inject`, `/stop`, `/status`) while loop is running
  230. - `--telegram-control-whisper`: enable Telegram voice/audio transcription for control messages (default on)
  231. ## Feishu Setup Checklist
  232. how to create a bot? [EN](Feishu_readme/Feishu_readme.md) [CN](Feishu_readme/Feishu_readme_CN.md)
  233. Use this when running in CN network environments or when Telegram is unavailable.
  234. Required parameters:
  235. - `--feishu-app-id`
  236. - `--feishu-app-secret`
  237. - `--feishu-chat-id` (for `receive_id_type=chat_id`, this should look like `oc_xxx`)
  238. Common optional parameters:
  239. - `--feishu-receive-id-type chat_id`
  240. - `--feishu-events "loop.started,round.review.completed,loop.completed"`
  241. - `--feishu-live-updates --feishu-live-interval-seconds 30`
  242. - `--feishu-heartbeat-interval-seconds 600`
  243. - `--feishu-control`
  244. Feishu group command notes:
  245. - Commands can be sent directly as `/run`, `/inject`, `/stop`, etc.
  246. - Mention-prefixed commands in groups (for example `@bot /stop`) are normalized and parsed as commands.
  247. Minimal run example:
  248. ```bash
  249. argusbot-run \
  250. --feishu-app-id "$FEISHU_APP_ID" \
  251. --feishu-app-secret "$FEISHU_APP_SECRET" \
  252. --feishu-chat-id "$FEISHU_CHAT_ID" \
  253. "your objective"
  254. ```
  255. App-side enablement steps (Feishu Open Platform):
  256. 1. Enable bot capability for the app.
  257. 2. Grant message-related app scopes (at least one required by API): `im:message.history:readonly`, `im:message:readonly`, or `im:message`.
  258. 3. Publish a new app version and install/update it in your tenant.
  259. 4. Add the bot into the target group, then use that group's `chat_id` (`oc_xxx`) in config.
  260. Common errors:
  261. - `230006 Bot ability is not activated`: bot capability is disabled or not published/installed yet.
  262. - `230002 Bot/User can NOT be out of the chat`: bot is not in the target group, or `feishu_chat_id` points to a different chat.
  263. - `99991672 Access denied ... scopes required`: required Feishu scopes are not enabled for the app.
  264. ## How to Instruct the System
  265. The most important field is the final goal. Put it first.
  266. A good objective usually has this shape:
  267. ```text
  268. Final Goal:
  269. <the end state you actually want>
  270. Current Task:
  271. <what should be done in this session>
  272. Acceptance Criteria:
  273. <how the system knows it is done>
  274. Constraints:
  275. <repo, time, safety, cost, model, dataset, or style constraints>
  276. Notes:
  277. <optional hints, references, known risks, or preferred approach>
  278. ```
  279. Practical guidance:
  280. - Put `Final Goal` first, even if the immediate task is small.
  281. - Say what “done” means in concrete terms.
  282. - If you want planner behavior, say whether it should explore, only record, or stay off.
  283. - If your wording is messy, you can ask any AI tool to rewrite your request into the template above before sending it here.
  284. - Optional: ArgusBot setup now includes an `Objective Rewrite` switch for `/run`. It is off by default, and it can rewrite a new idle `/run` request into this structure before handing it to the main agent.
  285. - Warning: keep that rewrite switch off for specialized projects unless it is clearly helping. 对于特化项目,建议按需开启,不要默认依赖它。
  286. ### Example 1: Reproduce a Paper
  287. Use this only when the paper has usable open-source code or a strong public implementation.
  288. ```text
  289. Final Goal:
  290. Reproduce the paper's core result well enough to run inference, complete one smoke training run, and generate a structured reproduction report in this repository.
  291. Current Task:
  292. Set up the repo, inspect the available code path, create the reproduction plan, wire the experiment directories, and run the minimum smoke path needed to prove the project is alive.
  293. Acceptance Criteria:
  294. 1. The repository has a clear plan_report.md and plan_todo.md.
  295. 2. The selected implementation path is documented.
  296. 3. At least one runnable inference or smoke-training command succeeds.
  297. 4. The next highest-priority follow-up experiment is recorded.
  298. Constraints:
  299. 1. Prefer official or high-quality open-source implementations.
  300. 2. Do not aim for full SOTA reproduction in the first session.
  301. 3. Keep the work resumable from Telegram and daemon state files.
  302. ```
  303. ### Example 2: Extend an Existing Project
  304. ```text
  305. Final Goal:
  306. Turn this repository into a maintainable, planner-driven project where completed work, remaining work, and next-step execution suggestions are always visible.
  307. Current Task:
  308. Map the architecture, identify the missing module boundaries, implement the highest-leverage missing feature, and update the project reports.
  309. Acceptance Criteria:
  310. 1. The new feature is implemented and validated.
  311. 2. Planner outputs reflect what is done and what remains.
  312. 3. The next follow-up objective is concrete enough to run as a new session.
  313. Constraints:
  314. 1. Preserve the existing coding style.
  315. 2. Prefer small verifiable steps over large speculative rewrites.
  316. ```
  317. Example with live dashboard (Do not expose yourself on the public internet! It's extremely dangerous!):
  318. ```bash
  319. argusbot-run \
  320. --dashboard \
  321. --dashboard-host 0.0.0.0 \
  322. --dashboard-port 8787 \
  323. --check "pytest -q" \
  324. "帮我在这个文件夹写一下pipeline"
  325. ```
  326. Then open `http://<your-machine-ip>:8787` on phone or browser.
  327. ## Safer cross-network monitoring (Telegram)
  328. If phone and server are not in the same network, do not expose dashboard publicly by default.
  329. Use Telegram push notifications instead:
  330. ```bash
  331. argusbot-run \
  332. --max-rounds 12 \
  333. --check "pytest -q" \
  334. --telegram-bot-token "$TELEGRAM_BOT_TOKEN" \
  335. --telegram-events "loop.started,round.review.completed,loop.completed" \
  336. "帮我在这个文件夹写一下pipeline"
  337. ```
  338. `--telegram-chat-id` defaults to `auto` and will be resolved from `getUpdates`.
  339. If auto resolve fails, send `/start` to bot and run again, or pass explicit chat id.
  340. Live visibility defaults:
  341. - Terminal prints main/reviewer agent messages in realtime.
  342. - Telegram sends live message deltas every 30 seconds only if there are new changes.
  343. Telegram control channel defaults:
  344. - `/inject <text>` or plain text message: interrupt current main-agent run and apply new instruction next round.
  345. - Voice/audio message: auto-transcribed via Whisper and treated like text input (for example spoken `/inject ...`).
  346. - `/status`: return current loop state.
  347. - `/stop`: interrupt current run and stop the loop.
  348. - `/help`: print command summary.
  349. Whisper-related options:
  350. - `--telegram-control-whisper-api-key`: OpenAI API key (defaults to `OPENAI_API_KEY`).
  351. - `--telegram-control-whisper-model`: transcription model (default `whisper-1`).
  352. - `--telegram-control-whisper-base-url`: OpenAI-compatible API base URL.
  353. - `--telegram-control-whisper-timeout-seconds`: transcription request timeout.
  354. Stall watchdog defaults:
  355. - If no new output for 1 hour, sub-agent inspects the latest message/tails and decides whether restart is needed.
  356. - If no new output reaches 3 hours, process is force-restarted regardless.
  357. Typing heartbeat is enabled by default during execution. Disable with:
  358. ```bash
  359. --telegram-no-typing
  360. ```
  361. Security notes:
  362. - Keep dashboard on `127.0.0.1` unless you have VPN/auth in front.
  363. - Never commit bot token to git.
  364. - Prefer sending round summaries, not every raw log line.
  365. Troubleshooting:
  366. - Bot token must be full format: `<digits>:<secret>`, not only the secret part.
  367. - If no message arrives, run once with `--verbose-events` and check stderr lines prefixed with `[telegram]`.
  368. - If control commands are ignored, verify command comes from the same chat id resolved for notifications.
  369. ## Always-on Telegram daemon (start jobs even when idle)
  370. If you want Telegram to trigger runs when no loop process is active, run:
  371. ```bash
  372. argusbot-daemon \
  373. --telegram-bot-token "$TELEGRAM_BOT_TOKEN" \
  374. --telegram-chat-id auto \
  375. --run-check "pytest -q"
  376. ```
  377. Daemon commands from Telegram:
  378. - `/run <objective>`: start a new `ArgusBot` run
  379. - `/status`: daemon/child status
  380. - `/stop`: stop active run
  381. - After `/stop`, use `/run <objective>` to continue. By default daemon resumes the last `session_id` when available.
  382. - `/help`
  383. - After a child run finishes, the daemon can offer a Telegram button to execute the planner's next suggested objective.
  384. - If the current session goal was confirmed with `/plan`, daemon may auto-execute the planned next session after the follow-up countdown (default: 10 minutes); otherwise auto follow-up is skipped and the user is reminded to confirm the session goal first.
  385. - Before executing that follow-up, daemon creates a git checkpoint commit when the workspace is dirty.
  386. - Telegram follow-up options are: direct execute, reject plan, or modify then execute while inheriting the planner objective. That follow-up starts as a fresh session.
  387. For background mode:
  388. ```bash
  389. TELEGRAM_BOT_TOKEN=... TELEGRAM_CHAT_ID=... ./scripts/start_telegram_daemon.sh
  390. ```
  391. Recommendation: prefer `systemd` or supervisor over raw `nohup` for production reliability.
  392. ## Interactive first-run setup (recommended)
  393. Run once:
  394. ```bash
  395. argusbot-setup --run-cd .
  396. ```
  397. If command is not found in your environment, use:
  398. ```bash
  399. python -m codex_autoloop.setup_wizard --run-cd .
  400. ```
  401. The wizard will:
  402. 1. Check the selected runner CLI availability and basic auth probe.
  403. 2. Prompt for control channel: Telegram, Feishu, or both.
  404. 3. Prompt only for the selected channel credentials.
  405. 4. Prompt optional default check command (empty means no forced check command).
  406. 5. Prompt for planner mode after model selection.
  407. 6. Start daemon in background and save config under `.argusbot/`.
  408. Default behavior for daemon-launched runs:
  409. - `--yolo` is enabled by default.
  410. - No default `--check` is enforced unless you set one.
  411. - Daemon-launched runs inherit the selected backend defaults unless you explicitly set preset/overrides.
  412. - When the daemon is idle, a new `/run` or terminal `run` command will reuse the last saved `session_id` if available.
  413. - One Telegram token can only be owned by one active daemon process (second daemon returns an error).
  414. - In daemon mode, only daemon polls Telegram updates; child runs receive control via daemon bus (avoids getUpdates 409 conflicts).
  415. - If daemon detects `invalid encrypted content` from a resumed run, it raises a warning and auto-arms fresh session for the next run.
  416. - Inside a running child loop, `invalid_encrypted_content` now triggers an immediate in-loop fresh-session retry instead of spinning reviewer `continue` loops.
  417. - Operator messages (initial objective + terminal/Telegram injects) are appended to a shared `.argusbot/logs/operator_messages.md` so reviewer can see global inject history across runs.
  418. - Each run also appends start/finish records into `.argusbot/logs/argusbot-run-archive.jsonl` (includes date + workspace + session metadata) for continuity and auditing.
  419. - Re-running setup or start script will stop the previous daemon under the same `home-dir` before launching the new one.
  420. After setup, use terminal control:
  421. ```bash
  422. argusbot-daemon-ctl --bus-dir .argusbot/bus run "帮我在这个文件夹写一下pipeline"
  423. argusbot-daemon-ctl --bus-dir .argusbot/bus inject "先修测试再继续"
  424. argusbot-daemon-ctl --bus-dir .argusbot/bus status
  425. argusbot-daemon-ctl --bus-dir .argusbot/bus stop
  426. argusbot-daemon-ctl --bus-dir .argusbot/bus daemon-stop
  427. ```
  428. One-click kill script:
  429. ```bash
  430. ./scripts/kill_telegram_daemon.sh
  431. ```
  432. Realtime log mirror:
  433. ```bash
  434. ./scripts/watch_argusbot_logs.sh .argusbot
  435. ```
  436. This mirrors:
  437. - `.argusbot/daemon.out`
  438. - `.argusbot/logs/daemon-events.jsonl` (Telegram/terminal control interactions)
  439. If `argusbot-daemon-ctl` is not found, replace it with:
  440. ```bash
  441. python -m codex_autoloop.daemon_ctl
  442. ```
  443. ## Model presets
  444. Show local model presets and common names:
  445. ```bash
  446. python -m codex_autoloop.model_catalog
  447. ```
  448. ### OpenAI / Codex Models
  449. Current presets:
  450. - `quality`: `main=gpt-5.4/high`, `reviewer=gpt-5.4/high`
  451. - `copilot`: `main=gpt-5.4/high`, `reviewer=gpt-5.4/high`
  452. - `codex52-xhigh`: `main=gpt-5.2-codex/xhigh`, `reviewer=gpt-5.2-codex/xhigh`
  453. - `quality-xhigh`: `main=gpt-5.4/xhigh`, `reviewer=gpt-5.4/xhigh`
  454. - `balanced`: `main=gpt-5.3-codex/high`, `reviewer=gpt-5.1-codex/medium`
  455. - `codex-xhigh`: `main=gpt-5.3-codex/xhigh`, `reviewer=gpt-5.3-codex/xhigh`
  456. - `cheap`: `main=gpt-5.1-codex-mini/medium`, `reviewer=gpt-5-codex-mini/low`
  457. - `max`: `main=gpt-5.1-codex-max/xhigh`, `reviewer=gpt-5.3-codex/high`
  458. ### Qwen Models (Alibaba Cloud DashScope)
  459. To use Qwen models, you need to set the following environment variables:
  460. ```bash
  461. # Set your Alibaba Cloud DashScope API Key
  462. export DASHSCOPE_API_KEY="your-dashscope-api-key"
  463. export DASHSCOPE_API_BASE="https://dashscope.aliyuncs.com/compatible-mode/v1"
  464. ```
  465. Get your API key from: https://dashscope.console.aliyun.com/
  466. Qwen presets:
  467. - `qwen3-quality`: `main=qwen3-30b-a3b/high`, `reviewer=qwen3-30b-a3b/high` - High quality Qwen3
  468. - `qwen3-balanced`: `main=qwen3-32b/high`, `reviewer=qwen3-14b/medium` - Balanced Qwen3
  469. - `qwen3-coder`: `main=qwen3-coder-32b/high`, `reviewer=qwen3-coder-14b/medium` - Code-optimized Qwen3
  470. - `qwen3-cheap`: `main=qwen3-coder-7b/medium`, `reviewer=qwen3-8b/low` - Budget Qwen3
  471. - `qwen25-quality`: `main=qwen2.5-max/high`, `reviewer=qwen2.5-max/high` - High quality Qwen2.5
  472. - `qwen25-balanced`: `main=qwen2.5-72b/high`, `reviewer=qwen2.5-32b/medium` - Balanced Qwen2.5
  473. - `qwen25-coder`: `main=qwen2.5-coder-32b/high`, `reviewer=qwen2.5-coder-14b/medium` - Code-optimized Qwen2.5
  474. - `qwen25-cheap`: `main=qwen2.5-coder-7b/medium`, `reviewer=qwen2.5-7b/low` - Budget Qwen2.5
  475. - `qwen35-quality`: `main=qwen3.5-72b/high`, `reviewer=qwen3.5-32b/high` - High quality Qwen3.5
  476. - `qwen35-balanced`: `main=qwen3.5-32b/high`, `reviewer=qwen3.5-14b/medium` - Balanced Qwen3.5
  477. - `qwen35-coder`: `main=qwen3.5-coder-32b/high`, `reviewer=qwen3.5-coder-14b/medium` - Code-optimized Qwen3.5
  478. - `qwen35-cheap`: `main=qwen3.5-coder-7b/medium`, `reviewer=qwen3.5-8b/low` - Budget Qwen3.5
  479. Note:
  480. - `gpt-5.4` is the model name.
  481. - `high` is the reasoning effort level, not part of the model name.
  482. - For always-on daemon use, `medium` is often the safer default for token cost while keeping solid quality.
  483. Daemon overrides:
  484. ```bash
  485. python -m codex_autoloop.setup_wizard --run-cd .
  486. ```
  487. The wizard now lets you choose either:
  488. - a preset for both agents, or
  489. - separate `main` / `reviewer` model names
  490. ## Example: Use in another project (`newproject`) with sanitized paths
  491. Use this pattern when `ArgusBot` is cloned under a different workspace and you want the daemon to run tasks in `newproject`.
  492. ```bash
  493. # Replace with your own locations (public-safe placeholders)
  494. export WORKSPACE_ROOT="/path/to/workspace"
  495. export LOOP_REPO="$WORKSPACE_ROOT/ArgusBot"
  496. export TARGET_REPO="$WORKSPACE_ROOT/newproject"
  497. cd "$TARGET_REPO"
  498. python -m pip install -e "$LOOP_REPO"
  499. # First-time setup (interactive)
  500. python -m codex_autoloop.setup_wizard \
  501. --run-cd "$TARGET_REPO" \
  502. --home-dir "$TARGET_REPO/.argusbot"
  503. ```
  504. After setup:
  505. ```bash
  506. # Terminal control (same running daemon)
  507. python -m codex_autoloop.daemon_ctl --bus-dir "$TARGET_REPO/.argusbot/bus" status
  508. python -m codex_autoloop.daemon_ctl --bus-dir "$TARGET_REPO/.argusbot/bus" run "run 100-step smoke and validate checkpoint+infer"
  509. python -m codex_autoloop.daemon_ctl --bus-dir "$TARGET_REPO/.argusbot/bus" inject "fix test failures first, then continue"
  510. ```
  511. Telegram control in parallel:
  512. - `/run <objective>`
  513. - `/inject <instruction>`
  514. - `/status`
  515. - `/stop`
  516. ## `codex --autoloop` style shim
  517. You can add a shell function so `codex --autoloop ...` routes to this plugin.
  518. ```bash
  519. codex() {
  520. if [[ " $* " == *" --autoloop "* ]]; then
  521. /data/yijia/ArgusBot/scripts/argusbot_shim.sh "$@"
  522. else
  523. command codex "$@"
  524. fi
  525. }
  526. ```
  527. Put it in `~/.bashrc` or `~/.zshrc`, then reload shell.
  528. ## Loop policy
  529. Per round:
  530. 1. Run main agent in the same Codex thread (`exec` then `exec resume`)
  531. 2. Run acceptance checks (`--check`, repeatable)
  532. 3. Run reviewer sub-agent with structured JSON schema output
  533. 4. Stop only if reviewer says `done` and all checks pass
  534. 5. Otherwise build a new continue prompt and run next round
  535. Safety stop conditions:
  536. - `max_rounds` reached
  537. - repeated no-progress rounds
  538. - reviewer returns `blocked`
  539. ## Contributing
  540. Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow, attribution, and acknowledgement details.
  541. ## License
  542. This project is licensed under the MIT License. See [LICENSE](LICENSE).
  543. ## Star History
  544. [![Star History Chart](https://api.star-history.com/svg?repos=waltstephen/ArgusBot&type=Date)](https://www.star-history.com/#waltstephen/ArgusBot&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.