Persistent, reviewed autonomy for research and engineering

Long-running agent work that can plan, execute, verify, pause, and continue beyond a single model turn.

Preview v0.1.2 · Official open-source release on the way.

Website · Video Demo · Technical Report · arXiv:2608.05144 · WeChat Community · English / 简体中文

Manager → Planner → Engineer ⇄ Reviewer

---

What is Argus?

Most agents are optimized for one conversation or one coding turn. Argus is built for work that lasts: it keeps state, separates execution from judgment, and resumes from verified progress instead of starting over.

Capability	What it means
Persistent state	Tasks, checkpoints, decisions, Skills, and evidence survive sessions and runtime upgrades.
Independent review	Execution and verification stay separate; normal rounds end with a Reviewer judgment.
Four-role runtime	Manager, Planner, Engineer, and Reviewer have distinct authority and responsibilities.
Real tool use	Agents work through files, terminals, experiments, APIs, and inspectable artifacts.
Domain extensibility	Verticals can define custom stages, tools, evidence requirements, and completion standards.
Multiple backends	Run with GitHub Copilot CLI, Pi, Codex CLI, Claude Code, OpenCode, Grok Build, Qoder, or DeepSeek Harness.

Runtime model

	Authority	Responsibility
01	Manager · Control	Interprets operator intent, selects the workflow, and owns stage transitions.
02	Planner · Direction	Chooses the next high-value task and defines the evidence it must produce.
03	Engineer · Execution	Implements, researches, runs experiments, and creates inspectable artifacts.
04	Reviewer · Verification	Independently checks correctness, evidence, limitations, and completion.

A project can stop, resume, survive a runtime replacement, and continue from its latest verified position.

Native backends: GitHub Copilot CLI · Pi · OpenAI Codex CLI · Claude Code · OpenCode · Grok Build · Qoder · DeepSeek Harness

Harbor evaluation: Harbor Framework can invoke the complete bounded Argus Manager/Planner/Engineer/Reviewer runtime as a custom agent. See Harbor integration.

Coding-agent plugin: use the packaged MCP bridge and host-specific Skills without changing the core runtime. See Plugin quick start.

WeChat community

Scan the QR code to join the Argus community. Click the image to open it at full size. If the printed expiry date has passed, open an Issue and ask the maintainers for the latest code.

Quick Install

Choose the section for your operating system. Do not mix commands between platforms. All platforms need Node.js 22.12+ from nodejs.org and one authenticated Agent CLI. Reuse the CLI you already work in; Argus does not require a separate account. Docker is not required for a normal Argus installation; it is only an optional prerequisite for the separate Harbor evaluation integration.

Tip

Recommended: let the Code Agent you already use install and verify Argus. Copy the prompt in the Agent-assisted section below. The manual commands remain available for users who prefer to install each step themselves.

Agent CLI	Backend	Install	Authenticate
GitHub Copilot CLI	copilot	npm install -g @github/copilot	copilot login
OpenAI Codex CLI	codex	npm install -g @openai/codex@latest	codex login
Claude Code	claude	npm install -g @anthropic-ai/claude-code	Run claude, then /login
Pi	pi	npm install -g --ignore-scripts @earendil-works/pi-coding-agent	Run pi, then /login
OpenCode	opencode	Official install	opencode auth login
Grok Build	grok	Official install	grok login
Qoder CLI	qoder	npm install -g @qoder-ai/qodercli	qodercli login
DeepSeek Harness	dsh	npm install -g @deepseek-ai/dsh	Configure DEEPSEEK_API_KEY or the dsh Models page

The public preview is installed directly from the current GitHub archive until the first PyPI release is published.

Recommended: Agent-assisted installation

Send this prompt to an already installed Code Agent:

Read https://github.com/lbx154/Argus/blob/main/docs/agent-install.md and install
Argus using the section for this operating system. Prefer the Agent CLI running
this conversation as the Argus backend. Do not create a venv on Windows or
macOS; keep the documented venv on Linux. Run setup through its real Agent-turn
smoke test, then run `argus doctor --deep --advisor auto`. Before account login,
sudo, or global configuration changes, explain why and wait for approval. Never
ask me to paste a password, token, or API key into the conversation.

The agent follows the installation execution contract.

Windows 10/11 — direct pip, no virtual environment

Install Python 3.11+ from python.org and select Add Python to PATH in the installer. Then open a new PowerShell:

py --version
node --version
py -m pip install --upgrade pip
py -m pip install --upgrade --force-reinstall "argus-skill @ https://github.com/lbx154/Argus/archive/refs/heads/main.zip"
$Scripts = py -c "import sysconfig; print(sysconfig.get_path('scripts'))"
$Argus = Join-Path $Scripts "argus.exe"
if (-not (Test-Path $Argus)) { throw "Argus entry point not found at $Argus" }
$env:Path = "$Scripts;$env:Path"
& $Argus --version
& $Argus --setup
& $Argus doctor --deep --advisor auto
& $Argus --status
& $Argus

Calling $Argus proves setup is not accidentally using another stale installation. $env:Path also makes plain argus available in the current PowerShell. The troubleshooting section covers persistent PATH repair.

argus doctor is an active repair command. By default it launches an installed Agent CLI in the real Argus directories with tools enabled, lets the Agent inspect and fix the machine, then reruns deterministic checks. Use argus doctor --advisor none --verify for a no-model verification. The active repair may take several minutes because it performs a real Agent turn; it is not a quick version check.

Windows currently supports installation, Manager chat, pairing, Web/TUI, terminal-scoped daemon control, and native durable subagents. On native Windows, a detached worker owns direct or supervised long commands, persists registry and log state, and uses bounded process-tree cleanup; WSL2 remains optional rather than required for this path. The Windows Desktop installer is documented separately in Windows Desktop.

macOS — managed command install, no manual virtual environment

Install uv if needed, then:

uv --version
node --version
uv tool install --force --python 3.12 \
  "argus-skill @ https://github.com/lbx154/Argus/archive/refs/heads/main.zip"
ARGUS_BIN="$(uv tool dir --bin)/argus"
test -x "$ARGUS_BIN"
"$ARGUS_BIN" --version
uv tool update-shell
"$ARGUS_BIN" --setup
"$ARGUS_BIN" doctor --deep --advisor auto
"$ARGUS_BIN" --status
"$ARGUS_BIN"

ARGUS_BIN works immediately even when uv's tool directory was not previously on PATH. uv tool update-shell makes plain argus available in a new terminal. uv tool already owns the isolated environment; do not create another venv.

Linux — isolated source venv

Linux servers keep an explicit venv so Python, CUDA tooling, and long-running process ownership remain reproducible. Install Python 3.11+, Git, Node.js 22.12+, and your distribution's python3-venv package first:

git clone https://github.com/lbx154/Argus.git "$HOME/Argus"
cd "$HOME/Argus"
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e .
ARGUS_BIN="$HOME/Argus/.venv/bin/argus"
"$ARGUS_BIN" --version
"$ARGUS_BIN" --setup
"$ARGUS_BIN" doctor --deep --advisor auto
"$ARGUS_BIN" --status
"$ARGUS_BIN"

Private-preview collaborators use https://github.com/lbx154/argus-skill.git in the Linux clone command. On Windows/macOS, install a private wheel or authenticated private archive rather than putting a GitHub token in shell history.

Do not rely on a globally installed argus on Linux. In a new shell, use $HOME/Argus/.venv/bin/argus (or activate that venv explicitly). If venv creation reports that ensurepip is unavailable, install the distribution's python3-venv package and rerun the command.

Backend notes

Use copilot, pi, codex, claude, opencode, grok, qoder, or dsh for --backend. Setup adopts a model from the selected CLI's own catalog when one is available; otherwise it keeps that CLI's native default. It does not inject an OpenAI model id into Claude Code, Pi, OpenCode, Grok, Qoder, or dsh. If you have an OpenAI-compatible endpoint, setup installs Pi when needed and configures it directly:

ARGUS_SETUP_API_KEY=... argus --setup --non-interactive \
  --api-url https://api.example.com/v1 \
  --api-model model-id

For Grok Build, install and authenticate the official xAI CLI first:

curl -fsSL https://x.ai/cli/install.sh | bash
grok login
argus --setup --non-interactive --backend grok

XAI_API_KEY is also supported for headless environments. Argus uses Grok's native headless JSON stream, resumes sessions by ID, and keeps role prompts out of process arguments. In PowerShell, use a backtick instead of \ for line continuation.

Choosing a provider on the multi-provider CLIs

Pi and OpenCode are provider-agnostic fronts: which account they bill depends on what you authenticated them against (a native DeepSeek key, Anthropic, Azure, a local vLLM, a Copilot proxy). Argus passes your configured model id straight through, so a bare id like deepseek-chat is resolved by the CLI itself.

Name the provider when a bare id is ambiguous or when the CLI requires it:

# Pi — only needed when two authenticated catalogs carry the same model id
export ARGUS_SKILL_PI_PROVIDER=deepseek

# OpenCode — required: `opencode run --model` only accepts provider/id
export ARGUS_SKILL_OPENCODE_PROVIDER=deepseek

Both are also settable from the cockpit /config view, and persist across restarts once set there.

argus --doctor reads the CLI's authenticated catalog and tells you when the configured provider is not one you hold a key for, or when a model id you selected is not on offer.

Use argus --config-help to inspect each role's effective model and where it came from. Catalog commands are backend-specific, for example pi --list-models, opencode auth list, and qodercli --list-models.

Full details, including the breaking change for Pi deployments that relied on the old implicit github-copilot prefix: backend providers.

Launch

Windows and macOS can use argus after PATH setup. On Linux, replace argus below with $HOME/Argus/.venv/bin/argus unless the venv is active.

argus

argus doctor                         # Agent-driven inspection and repair
argus doctor --advisor none --verify # deterministic verification, no model call
argus --status                       # inspect the current runtime

Interfaces

Windows Desktop

The Windows x64 source tree includes an Electron host that supervises a frozen copy of the same Argus runtime and opens the existing Web cockpit—there is no separate Desktop fork of Manager, Workbench, or the WebAPI. Source setup, security boundaries, verification, and packaging commands are documented in Windows Desktop.

Terminal cockpit

argus

Use the terminal cockpit to talk to the Manager, follow live work, inspect state, and resume projects. Without an explicit --port, Argus reuses a compatible backend or selects the first available port starting at 8799 when another program or stale backend occupies it. On Windows, a plain argus launch also opens the Web UI; use argus --no-open for the terminal cockpit only.

Web UI

Start Argus and open the Web UI in your default browser:

argus --web

Preferred address: http://127.0.0.1:8799; Argus advances to the next available port when needed.

The Web UI follows the browser language on first launch and supports English and Simplified Chinese. Use the language button in the session sidebar to switch; the selection is saved in the browser.

argus --web --web-port 8800  # use another port

Remote server over SSH

On the server:

argus --web

On your computer:

ssh -L 8799:127.0.0.1:8799 user@server

Then open http://127.0.0.1:8799 locally.

Direct LAN access

A non-loopback bind is always protected by a bearer token. If ARGUS_SKILL_WEB_TOKEN is set it is used; otherwise one is minted for that run:

argus --web --web-host 0.0.0.0 --web-port 8799

This prints the address other devices can reach, the token, and a QR code. Set the token yourself to keep one across restarts:

export ARGUS_SKILL_WEB_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

To serve without a token — only behind your own authenticating proxy — set ARGUS_SKILL_WEB_ALLOW_INSECURE=1.

From a phone

Telegram, Feishu/Lark, and the web UI all work from a phone. The two chat bots dial out, so a daemon behind NAT needs no tunnel and no public URL:

# Feishu / Lark — WebSocket long connection, no request URL to configure
pip install 'argus-skill[feishu]'
export ARGUS_SKILL_ENABLE_FEISHU=1
export ARGUS_SKILL_FEISHU_APP_ID=cli_xxx ARGUS_SKILL_FEISHU_APP_SECRET=xxx

# Telegram
export ARGUS_SKILL_ENABLE_TELEGRAM=1
export ARGUS_SKILL_TELEGRAM_BOT_TOKEN=... ARGUS_SKILL_TELEGRAM_CHAT_ID=...

Both bots serve the same commands (/add, /status, /nudge, /backlog, …). The web UI is installable to the home screen and pairs by scanning the QR code printed by argus --web --web-host 0.0.0.0.

See docs/mobile.md for the full setup.

Advanced usage

Argus is designed to be changed, not merely configured.

Autonomy level

The default pragmatic mode handles recoverable engineering choices—timeouts, failed tests, benchmark sizing, and technical routes—without interrupting you. It asks only for credentials, more spending, irreversible/outward-facing actions, or changes to an operator-owned acceptance boundary.

export ARGUS_SKILL_AUTONOMY_MODE=cautious    # ask on every explicit question
export ARGUS_SKILL_AUTONOMY_MODE=pragmatic   # default: recover technical issues
export ARGUS_SKILL_AUTONOMY_MODE=autonomous  # maximize reversible execution

The Web configuration view and /config expose the same setting.

Adapt the runtime

If you are an agent enthusiast, deploy Argus locally and make the complete loop fit the way you work. Tune role prompts, workflow boundaries, review policy, tools, and operating conventions; connect your own infrastructure; preserve the behavior you care about with tests.

Build your own Vertical

A Vertical gives your field its own stages, Skills, datasets, tools, evidence expectations, evaluation methods, and completion criteria. Planning and review can then follow the real standards of your domain instead of a generic process.

Use another agent as the outer layer

GitHub Copilot, Pi, Codex, Claude Code, OpenCode, Grok Build, OpenClaw, or Hermes can be the environment from which you invoke Argus, inspect its state, operate its local CLI or Web/API surface, and continue improving the deployment.

• Native Argus backends: GitHub Copilot CLI, Pi, Codex CLI, Claude Code, OpenCode, Grok Build, Qoder, DeepSeek Harness
• External agent operators: OpenClaw, Hermes, or any agent that can use a shell or HTTP API

For durable missions, install or adapt the portable argus-runtime-orchestration Agent Skill. It defines the two-party operator model, the active Needs you intervention loop, host-specific adapters, evidence boundaries, and closeout checks.

Useful entry points:

argus doctor
argus --status
argus --web

The most capable setup is often an Argus instance deliberately adapted to your own ambitious field and way of working.

Update

Windows:

py -m pip install --upgrade --force-reinstall "argus-skill @ https://github.com/lbx154/Argus/archive/refs/heads/main.zip"
$Argus = Join-Path (py -c "import sysconfig; print(sysconfig.get_path('scripts'))") "argus.exe"
& $Argus --version
& $Argus doctor --advisor none --verify

macOS:

uv tool install --force --python 3.12 \
  "argus-skill @ https://github.com/lbx154/Argus/archive/refs/heads/main.zip"
"$(uv tool dir --bin)/argus" --version
"$(uv tool dir --bin)/argus" doctor --advisor none --verify

Linux source checkout:

"$HOME/Argus/.venv/bin/argus" update
"$HOME/Argus/.venv/bin/argus" --version
"$HOME/Argus/.venv/bin/argus" doctor --advisor none --verify

The Linux source command refuses dirty or detached checkouts, fast-forwards the configured upstream, and refreshes the editable installation when the revision changes. Argus detects stale local WebAPI and daemon processes and replaces them at a controlled task boundary. Update verification is deterministic and does not spend a model call.

Uninstall

# Windows
py -m pip uninstall argus-skill

# macOS
uv tool uninstall argus-skill

On Linux, stop Argus, preserve any work you need, then remove the $HOME/Argus checkout and its .venv. Package removal intentionally leaves runtime state under $HOME/.argus-skill untouched on every platform; delete that directory only when you also want to remove projects, configuration, and logs.

Installation troubleshooting

• Confirm which executable the shell is using: Get-Command argus -All on PowerShell, or type -a argus on macOS/Linux. Its argus --version release id should change after an update.
• On macOS, use "$(uv tool dir --bin)/argus" immediately. Run uv tool update-shell once and open a new terminal for plain argus.
• On Windows, recover the exact Scripts directory with $Scripts = py -c "import sysconfig; print(sysconfig.get_path('scripts'))". Add it to the current window with $env:Path = "$Scripts;$env:Path". For new windows, use the Python installer’s Modify action and enable Add Python to PATH rather than creating a venv.
• On Linux, use $HOME/Argus/.venv/bin/argus; a global argus may be an older installation. Install python3-venv if python3 -m venv lacks ensurepip.
• Use argus doctor --advisor none --verify for deterministic diagnostics. Use argus doctor when you want an installed Agent to inspect and repair Argus directly.
• Use argus --config-help to check the effective backend/model before blaming setup or authentication.