diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 00000000..d5822d8f
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,151 @@
+name: release
+
+on:
+ push:
+ tags:
+ - "v*"
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ python:
+ name: build · wheel + sdist
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: "22.12.0"
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+ - name: Install build dependencies
+ run: |
+ python -m pip install --upgrade pip
+ python -m pip install -e . build
+ npm --prefix frontend/web ci
+ npm --prefix frontend/tui ci
+ - name: Build release sources
+ run: python -m argus_skill.release_tools.build_release
+ - name: Validate tag and package versions
+ if: startsWith(github.ref, 'refs/tags/v')
+ run: |
+ python - <<'PY'
+ import json
+ import os
+ import tomllib
+ from pathlib import Path
+
+ python_version = tomllib.loads(
+ Path("pyproject.toml").read_text(encoding="utf-8")
+ )["project"]["version"]
+ desktop_version = json.loads(
+ Path("desktop/package.json").read_text(encoding="utf-8")
+ )["version"]
+ tag = os.environ["GITHUB_REF_NAME"]
+ assert tag == f"v{python_version}", (
+ f"tag {tag!r} does not match Python package version {python_version!r}"
+ )
+ assert desktop_version == python_version, (
+ f"Desktop version {desktop_version!r} does not match "
+ f"Python package version {python_version!r}"
+ )
+ PY
+ - name: Build distributions
+ run: python -m build
+ - name: Clean-install wheel smoke
+ run: |
+ python -m venv /tmp/argus-wheel-smoke
+ /tmp/argus-wheel-smoke/bin/python -m pip install dist/*.whl
+ /tmp/argus-wheel-smoke/bin/argus-skill --version
+ /tmp/argus-wheel-smoke/bin/python - <<'PY'
+ from pathlib import Path
+ import argus_skill
+ root = Path(argus_skill.__file__).parent
+ assert (root / "_frontend/web/dist/index.html").is_file()
+ assert (root / "_frontend/tui/bundle/argus.mjs").is_file()
+ PY
+ - uses: actions/upload-artifact@v4
+ with:
+ name: python-dist
+ path: dist/*
+
+ windows:
+ name: build · Windows installers
+ runs-on: windows-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: "22.12.0"
+ cache: npm
+ cache-dependency-path: |
+ frontend/web/package-lock.json
+ frontend/tui/package-lock.json
+ desktop/package-lock.json
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+ - name: Install build dependencies
+ run: |
+ python -m pip install --upgrade pip
+ python -m pip install -e . "pyinstaller>=6.11,<7"
+ npm --prefix frontend/web ci
+ npm --prefix frontend/tui ci
+ npm --prefix desktop ci
+ - name: Build release sources
+ run: python -m argus_skill.release_tools.build_release
+ - name: Build frozen backend
+ shell: pwsh
+ run: ./desktop/scripts/build-backend.ps1 -SkipInstall
+ - name: Build Desktop
+ run: npm --prefix desktop run build
+ - name: Build unsigned installer and portable executable
+ working-directory: desktop
+ run: >-
+ npx electron-builder --win nsis portable --publish never
+ --config.win.signAndEditExecutable=false
+ - uses: actions/upload-artifact@v4
+ with:
+ name: windows-installers
+ path: desktop/release/*.exe
+
+ pypi:
+ name: publish · PyPI
+ if: startsWith(github.ref, 'refs/tags/v')
+ needs: [python, windows]
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ id-token: write
+ environment:
+ name: pypi
+ url: https://pypi.org/project/argus-skill/
+ steps:
+ - uses: actions/download-artifact@v4
+ with:
+ name: python-dist
+ path: dist
+ - uses: pypa/gh-action-pypi-publish@release/v1
+
+ github:
+ name: publish · GitHub Release
+ if: startsWith(github.ref, 'refs/tags/v')
+ needs: [python, windows]
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write
+ steps:
+ - uses: actions/download-artifact@v4
+ with:
+ name: python-dist
+ path: release-assets
+ - uses: actions/download-artifact@v4
+ with:
+ name: windows-installers
+ path: release-assets
+ - uses: softprops/action-gh-release@v2
+ with:
+ files: release-assets/**/*
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index a593ce0e..6305caab 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -60,10 +60,16 @@ env:
tests/daemon/test_spawn_helper.py
tests/daemon/test_windows_daemon_control.py
tests/daemon/test_windows_terminal_process.py
+ tests/core/test_agent_probe.py
+ tests/core/test_backend_readiness.py
+ tests/core/test_cheap_route_models.py
tests/maintenance/test_repair_pipeline.py
+ tests/maintenance/test_doctor_advisor.py
tests/test_agent_cli_backend.py
tests/test_bootstrap_doctor.py
tests/test_doctor.py
+ tests/test_install_documentation.py
+ tests/tools/test_setup_readiness.py
tests/webapi/test_commands_m1.py
tests/webapi/test_server_m0.py
tests/webapi/test_workspace_v2.py
@@ -126,6 +132,28 @@ jobs:
- name: Test portable surface
run: python -m pytest -q ${{ env.PORTABLE_TESTS }}
+ - uses: astral-sh/setup-uv@v5
+ if: runner.os == 'macOS'
+ - name: Smoke macOS uv tool install
+ if: runner.os == 'macOS'
+ run: |
+ export UV_TOOL_DIR="$RUNNER_TEMP/argus-tools"
+ export UV_TOOL_BIN_DIR="$RUNNER_TEMP/argus-bin"
+ uv tool install --python 3.12 .
+ "$UV_TOOL_BIN_DIR/argus-skill" --version
+ "$UV_TOOL_BIN_DIR/argus" --help
+
+ - name: Smoke Windows direct pip install
+ if: runner.os == 'Windows'
+ shell: pwsh
+ run: |
+ python -m pip install build
+ python -m build --wheel
+ python -m pip uninstall -y argus-skill
+ python -m pip install --no-deps (Get-ChildItem dist\*.whl).FullName
+ argus-skill --version
+ argus --help
+
# The pairing banner is written to stderr, which on Windows uses the ANSI
# code page (cp1252/cp936) whenever output is redirected — not UTF-8.
# Printing a QR code there used to raise UnicodeEncodeError and abort
diff --git a/README.md b/README.md
index 6641b69e..78676da1 100644
--- a/README.md
+++ b/README.md
@@ -36,7 +36,7 @@ Most agents are optimized for one conversation or one coding turn. Argus is buil
| **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. |
+| **Multiple backends** | Run with GitHub Copilot CLI, Pi, Codex CLI, Claude Code, OpenCode, or Grok Build. |
## Runtime model
@@ -49,75 +49,119 @@ Most agents are optimized for one conversation or one coding turn. Argus is buil
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`
+**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](docs/harbor.md)**.
+**Coding-agent plugin:** use the packaged MCP bridge and host-specific Skills
+without changing the core runtime. See **[Plugin quick start](docs/plugin.md)**.
+
## Quick Install
-### Requirements
+Choose the section for your operating system. Do not mix commands between
+platforms.
-- Python 3.11+
-- Node.js 22+
-- One supported Agent CLI installed and authenticated through its official login flow
+All platforms need:
-### 🚀 Agent-assisted installation (recommended)
+- one supported Agent CLI already installed;
+- that CLI authenticated through its official login flow;
+- Node.js 22+ for the terminal cockpit.
-> [!TIP]
-> **Skip the manual installation steps.** Send the complete prompt below to
-> Codex CLI, Claude Code, GitHub Copilot CLI, Pi, OpenCode, or Grok Build. The agent will
-> inspect the environment, install Argus, connect the current backend, and
-> verify it with `argus --doctor`.
+The public preview is installed directly from the current GitHub archive until
+the first PyPI release is published.
-```text
-Read https://github.com/lbx154/Argus/blob/main/docs/agent-install.md and follow
-it to install and configure Argus on my machine. Prefer the Agent CLI currently
-running this conversation as the Argus backend. Perform the environment checks,
-installation, configuration, and argus --doctor verification. Before account
-login, sudo, global configuration changes, or any other action requiring human
-authorization, explain why and wait for my approval. Never ask me to paste a
-password, access token, or API key into the conversation.
+### Windows 10/11 — direct pip install, no virtual environment
+
+Install Python 3.11+ from [python.org](https://www.python.org/downloads/windows/)
+and select **Add Python to PATH** in the installer. Then open a new PowerShell:
+
+```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
```
-The agent will follow the **[installation execution contract](docs/agent-install.md)**.
+`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.
-### Install
+Until the first versioned PyPI release, refresh the moving GitHub preview with:
-```bash
-git clone https://github.com/lbx154/Argus.git
-cd Argus
+```powershell
+py -m pip install --upgrade --force-reinstall "argus-skill @ https://github.com/lbx154/Argus/archive/refs/heads/main.zip"
```
-Linux and macOS:
+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](docs/windows-desktop.md)**.
+
+### macOS — managed command install, no manual virtual environment
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then:
```bash
-python3 -m venv .venv
-. .venv/bin/activate
-python -m pip install --upgrade pip
-python -m pip install -e .
+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
```
-Windows PowerShell:
+Upgrade later with:
-```powershell
-python -m venv .venv
-.\.venv\Scripts\python.exe -m pip install --upgrade pip
-.\.venv\Scripts\python.exe -m pip install -e .
+```bash
+uv tool install --force --python 3.12 \
+ "argus-skill @ https://github.com/lbx154/Argus/archive/refs/heads/main.zip"
```
-The Windows commands call the virtual environment directly, so activation is
-not required. Before using the shorter `argus` commands below, either run
-`.\.venv\Scripts\Activate.ps1` or invoke `.\.venv\Scripts\argus.exe` directly.
+### Linux — isolated source venv
-### Connect a backend
+Linux servers keep an explicit venv so Python, CUDA tooling, and long-running
+process ownership remain reproducible:
```bash
-argus --setup
+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
```
-Use `copilot`, `pi`, `codex`, `claude`, `opencode`, `grok`, `qoder`, or `dsh` for `--backend`.
+### Agent-assisted installation
+
+Send this prompt to an already installed Code Agent:
+
+```text
+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](docs/agent-install.md)**.
+
+### 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:
@@ -138,6 +182,7 @@ 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
@@ -163,6 +208,10 @@ restarts once set there.
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](docs/backend-providers.md)**.
@@ -177,10 +226,6 @@ argus --doctor # verify the installation
argus --status # inspect the current runtime
```
-### Codex / Claude Code plugin
-
-One-command installation and usage: [docs/plugin.md](docs/plugin.md).
-
## Interfaces
### Windows Desktop
@@ -219,8 +264,7 @@ and Simplified Chinese. Use the language button in the session sidebar to
switch; the selection is saved in the browser.
```bash
-argus --web --no-open # start without opening a browser
-argus --web --port 8800 # use another port
+argus --web --web-port 8800 # use another port
```
#### Remote server over SSH
@@ -228,7 +272,7 @@ argus --web --port 8800 # use another port
On the server:
```bash
-argus --web --no-open
+argus --web
```
On your computer:
@@ -246,7 +290,7 @@ 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:
```bash
-argus --web --host 0.0.0.0 --port 8799 --no-open
+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.
@@ -279,7 +323,7 @@ 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 --host 0.0.0.0`.
+printed by `argus --web --web-host 0.0.0.0`.
See **[docs/mobile.md](docs/mobile.md)** for the full setup.
@@ -287,6 +331,18 @@ See **[docs/mobile.md](docs/mobile.md)** for the full setup.
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.
+
+```bash
+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.
@@ -302,31 +358,50 @@ GitHub Copilot, Pi, Codex, Claude Code, OpenCode, Grok Build, OpenClaw, or Herme
- **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](integrations/agent-skills/argus-runtime-orchestration/SKILL.md).
+It defines the two-party operator model, the active `Needs you` intervention loop,
+host-specific adapters, evidence boundaries, and closeout checks.
+
Useful entry points:
```bash
-argus --doctor
+argus doctor
argus --status
-argus --web --no-open
+argus --web
```
The most capable setup is often an Argus instance deliberately adapted to your own ambitious field and way of working.
## Update
+Windows:
+
+```powershell
+pip install --upgrade "argus-skill @ https://github.com/lbx154/Argus/archive/refs/heads/main.zip"
+```
+
+macOS:
+
+```bash
+uv tool upgrade argus-skill
+```
+
+Linux source checkout:
+
```bash
argus update
```
-The command refuses dirty or detached checkouts, fast-forwards the configured
+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. This code is valid through August 20, 2026; if it has expired, open an Issue and ask the maintainers for the latest code.
+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.