Skip to content

agent-install.md

Latest commit

 

History

History
275 lines (214 loc) · 10.2 KB

agent-install.md

File metadata and controls

275 lines (214 loc) · 10.2 KB
Raw

Argus installation instructions for coding agents

Complete the installation; do not merely print commands.

Installation channel

The commands below use the official source repository, microsoft/ArgusAgent. They install its main branch, not a published binary release and not a PyPI package. Use the development preview, lbx154/Argus, only when the user asks for it; replace the repository in the selected platform's commands and use this guide from that same repository.

For an upgrade, inspect the existing checkout remote or the installed package's direct_url.json before choosing the source. Keep the existing channel unless the user requests a switch. Never silently redirect an existing clone.

Windows packaged previews are separate from source installation. See Windows Desktop for the official and preview release pages; an EXE may not yet contain fixes present on main.

Safety contract

  • Argus has no separate Argus account. Use one supported Agent CLI and its official login flow.
  • Inspect before changing the machine.
  • Ask before sudo, system package installation, shell startup edits, or global configuration changes.
  • Never request passwords, tokens, or API keys in chat. Never place credentials in the Argus checkout or shell history.
  • Prefer the Agent CLI already running this conversation.
  • Do not replace a dirty checkout or silently switch providers after a failure.
  • Use only the section for the detected operating system.
  • Running argus doctor is read-only. Only an explicit argus doctor --advisor <auto|backend> authorizes the selected installed Agent to inspect and repair Argus files, configuration, runtime state, and required dependencies. Login or administrator blockers must be reported rather than guessed.

Supported backend values:

Agent CLI Backend
GitHub Copilot CLI copilot
OpenAI Codex CLI codex
Claude Code claude
Cursor CLI cursor
Pi pi
OpenCode opencode
xAI Grok Build grok
Qoder CLI qoder
DeepSeek Harness dsh

Setup adopts a model from the selected CLI's own catalog when available and otherwise keeps its native default. Never assign an OpenAI model id to Claude Code, Pi, OpenCode, Grok, Qoder, or dsh merely because it is Argus's historical default.

Windows 10/11

Inspect

Use PowerShell:

[Environment]::OSVersion.VersionString
py --version
node --version
Get-Command copilot,codex,claude,agent,cursor-agent,pi,opencode,grok,qodercli,dsh -ErrorAction SilentlyContinue

Require Python 3.11+ from python.org with Add Python to PATH selected, Node.js 22.12+, and one authenticated Agent CLI.

Install — no virtual environment

py -m pip install --upgrade pip
py -m pip install --upgrade --force-reinstall "argus @ https://github.com/microsoft/ArgusAgent/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

Do not ask the user to create or activate a venv on Windows. A packaged Desktop installer may be used instead when a release provides one.

Always retain --force-reinstall while installing the moving preview: its package version may stay unchanged when the archive contents change.

Configure and verify

& $Argus --setup --non-interactive --backend <copilot|codex|claude|cursor|pi|opencode|grok|qoder|dsh>
& $Argus doctor --deep --advisor auto
& $Argus --status

argus --setup must finish its real Agent-turn smoke test. A package install or version command alone is not success. Using $Argus proves the newly installed entry point was tested instead of another copy earlier on PATH. If a later window cannot find plain argus, report $Scripts and ask before changing the user PATH; do not create a venv as a workaround.

Windows supports Manager chat, pairing, Web/TUI, terminal-scoped daemon control, and native durable subagents. Native Windows workers own direct or supervised long commands, persist registry and log state, and perform bounded process-tree cleanup. WSL2 is optional, not a prerequisite for this path.

macOS

Inspect

sw_vers
uname -m
uv --version
node --version
for cli in copilot codex claude agent cursor-agent pi opencode grok qodercli dsh; do command -v "$cli" || true; done

Require Node.js 22.12+, one authenticated Agent CLI, and uv. Install uv only with the user's approval and its official installer.

Install — uv-managed command, no manual venv

uv tool install --force --python 3.12 \
  "argus @ https://github.com/microsoft/ArgusAgent/archive/refs/heads/main.zip"
ARGUS_BIN="$(uv tool dir --bin)/argus"
test -x "$ARGUS_BIN"
"$ARGUS_BIN" --version

Configure and verify

"$ARGUS_BIN" --setup --non-interactive \
  --backend <copilot|codex|claude|cursor|pi|opencode|grok|qoder|dsh>
"$ARGUS_BIN" doctor --deep --advisor auto
"$ARGUS_BIN" --status

Setup is complete only after the real Agent-turn smoke succeeds. Keep using $ARGUS_BIN in the current shell. With approval, run uv tool update-shell to make plain argus available in new terminals.

With the explicit --advisor auto shown above, Doctor runs the installed Agent with tools enabled, applies Argus-scoped repairs, and then reruns deterministic verification. argus doctor without an advisor remains read-only; use --advisor none --verify for an explicit non-Agent verification run. Allow several minutes for an active repair because it performs a real Agent turn and may repair dependencies.

Linux

Inspect

uname -a
python3 --version
node --version
git --version
for cli in copilot codex claude agent cursor-agent pi opencode grok qodercli dsh; do command -v "$cli" || true; done

Require Python 3.11+, Node.js 22.12+, Git, the distribution's python3-venv package, and one authenticated Agent CLI.

Install — persistent source venv

Choose a persistent directory. Default to $HOME/Argus only when it does not already contain unrelated data:

git clone https://github.com/microsoft/ArgusAgent.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

Private-preview collaborators may use the authorized private repository instead. If the checkout already exists, inspect git status; update only a clean branch with git pull --ff-only, then refresh the editable install.

Configure and verify

cd "$HOME/Argus"
"$ARGUS_BIN" --setup --non-interactive \
  --backend <copilot|codex|claude|cursor|pi|opencode|grok|qoder|dsh>
"$ARGUS_BIN" doctor --deep --advisor auto
"$ARGUS_BIN" --status

Linux keeps the explicit venv because server Python/CUDA dependencies and long-running process ownership must remain reproducible. Never substitute a global argus; it may be stale. If venv creation reports missing ensurepip, install the distribution's python3-venv package and retry.

Confirm the backend model selector

Setup validates the model it will send before reporting success. Also run <exact-argus-executable> --config-help and inspect each role's effective value and source. Backend catalog commands include pi --list-models, opencode auth list, and qodercli --list-models. If the selected id is not in that account's catalog, set ARGUS_SKILL_MODEL or a role-specific model knob before rerunning setup. Do not silently switch providers after a failed readiness check.

OpenAI-compatible endpoint

Setup can configure Pi directly:

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

If PI_CODING_AGENT_DIR is set, setup writes models.json in that directory, matching the Pi CLI. Otherwise it uses ~/.pi/agent/models.json. Keep the same environment when launching Argus so Pi reads the configuration that setup wrote.

On Windows use a PowerShell environment variable and backtick continuation. On macOS/Linux replace argus with the exact executable established above. Never paste the key into chat or commit it.

Upgrade and deterministic verification

Use argus update with the exact executable established during installation. argus --update and argus -update are equivalent aliases. This updater handles source checkouts, pip ZIP installations, and uv-managed installations while preserving the existing source and channel. It selects the corresponding package manager; source checkouts must be clean and on a branch, and only fast-forward updates are allowed.

When PATH is not configured, use & $Argus update in Windows PowerShell, "$(uv tool dir --bin)/argus" update for uv, or "$HOME/Argus/.venv/bin/argus" update for the Linux source checkout.

Older versions do not include this updater. Bootstrap once using the original installation command on Windows/macOS, including --force-reinstall/--force and the existing repository URL. For a source checkout, inspect its local changes and configured upstream first; only on a clean, attached branch run git pull --ff-only, then reinstall with that environment's Python using -m pip install -e .. Never change channels to bootstrap the updater.

After an upgrade, run the exact executable with --version and doctor --advisor none --verify. Do not invoke a second Agent repair turn merely to prove an unchanged installation.

Packaged Desktop EXEs use their separate signed desktop update channel. The CLI updater does not replace a signed EXE; use the Windows Desktop instructions for those installations.

Completion report

Report:

  • operating system and installation method;
  • exact executable used for Argus;
  • selected Agent CLI/backend;
  • effective model and configuration source for each role;
  • whether setup's real Agent turn passed;
  • whether argus doctor --deep --advisor auto passed;
  • exact launch command;
  • remaining manual login or PATH action.

If setup or Doctor fails, report the failing stage, executable, concise error, and exact next command. Do not claim installation success.