lbx154/argus

---

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.

Runtime model

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

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.

Quick Install

Choose the section for your operating system. Do not mix commands between platforms.

All platforms need:

• one supported Agent CLI already installed;
• that CLI authenticated through its official login flow;
• Node.js 22+ for the terminal cockpit.

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

Windows 10/11 — direct pip install, 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 -m pip install --upgrade pip
py -m pip install --upgrade "argus-skill @ https://github.com/lbx154/Argus/archive/refs/heads/main.zip"
$Scripts = py -c "import sysconfig; print(sysconfig.get_path('scripts'))"
$env:Path = "$Scripts;$env:Path"
argus --setup
argus doctor --deep --advisor auto
argus

argus --setup does not report success after only finding the CLI. It performs backend/auth checks and one real tool-restricted Agent turn. If argus is not found in a later PowerShell window, confirm that the Python installer’s Scripts directory is on PATH; the $Scripts lines above make it available immediately in the current window.

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 only when you want diagnostics without an Agent repair turn.

Until the first versioned PyPI release, refresh the moving GitHub preview with:

py -m pip install --upgrade --force-reinstall "argus-skill @ https://github.com/lbx154/Argus/archive/refs/heads/main.zip"

Windows currently supports installation, Manager chat, pairing, Web/TUI, and terminal-scoped daemon control. Detached subagents remain a POSIX/WSL2 feature; native Windows fails explicitly instead of claiming a background task started. The Windows Desktop installer is documented separately in Windows Desktop.

macOS — managed command install, no manual virtual environment

Install uv, then:

uv tool install --python 3.12 \
  "argus-skill @ https://github.com/lbx154/Argus/archive/refs/heads/main.zip"
argus --setup
argus doctor --deep --advisor auto
argus

Upgrade later with:

uv tool install --force --python 3.12 \
  "argus-skill @ https://github.com/lbx154/Argus/archive/refs/heads/main.zip"

Linux — isolated source venv

Linux servers keep an explicit venv so Python, CUDA tooling, and long-running process ownership remain reproducible:

git clone https://github.com/lbx154/Argus.git
cd Argus
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e .
.venv/bin/argus --setup
.venv/bin/argus doctor --deep --advisor auto
.venv/bin/argus

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.

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 the effective model and its source for each role. Catalog listing is backend-specific, for example pi --list-models, opencode auth list, or qodercli --list-models.

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

Launch

argus

argus --doctor   # verify the installation
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.

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
• 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:

pip install --upgrade "argus-skill @ https://github.com/lbx154/Argus/archive/refs/heads/main.zip"

macOS:

uv tool upgrade argus-skill

Linux source checkout:

argus update

The Linux source command refuses dirty or detached checkouts, fast-forwards the configured upstream, and refreshes the editable installation when the revision changes. Run argus afterward; it detects stale local WebAPI and daemon processes and replaces them at a controlled task boundary.

WeChat community

Scan the QR code below to join the Argus community. The expiry date is printed in the image; if it has expired, open an Issue and ask the maintainers for the latest code.