# Install Argus (the adengine command)

> Argus is a local MCP server and a set of skills that turn the AI agent you already use into an ad production team for e-commerce video ads. Its command, its MCP server and its skills are named `adengine`. This guide tells an AI agent how to install Argus for its user. The same guide is at https://runargusapp.com/agents as a web page.

## Identity

- Product: Argus, from https://runargusapp.com.
- Commands: `adengine` and `adengine-mcp`. MCP server name: `adengine`. Skill names: `adengine-*`, starting with `adengine-setup`.
- Installers: https://runargusapp.com/install.sh (macOS and Linux) and https://runargusapp.com/install.ps1 (Windows). Both open with a "Before you run it" summary that matches this guide.
- Other projects share these names. The GitHub project ruydt/argus is a different product with its own installer, and the `adengine` package on PyPI is unrelated. Install neither. The Argus installer never uses PyPI's `adengine`.

## Objective

Run the Argus installer once for the user, in the foreground, outside your sandbox. Relay its result. Run the ffmpeg follow-up step when the installer prints one, and ask the user before the optional editor step. Then tell the user to restart their agent and give them the first prompt for that agent. Do not try to call Argus tools or the setup skill in the session that ran the installer: they load only in a new session.

## What the installer does

1. Checks, before any download, that it can reach the network and write to the home folder. Inside a sandbox it stops within seconds with exit code 10 or 11 and prints the permission to ask for.
2. Asks https://runargusapp.com/api/releases/latest for the current release, downloads the wheel and checks its SHA-256. A mismatch installs nothing.
3. Installs uv from astral.sh when it is missing, then installs the wheel with `uv tool install`. uv adds Python 3.12 when the computer needs it.
4. Runs `adengine setup --yes --json --core`, which registers the `adengine` MCP server and the `adengine-*` skills with every supported agent it finds on the computer.
5. Prints any optional follow-up steps, a restart line and a last line that starts with `ARGUS_RESULT`.

## What it changes

- `~/.adengine`: the workspace, the verified release and backups of every config file it edits.
- uv's folders: `~/.local/bin` (`adengine`, `adengine-mcp` and uv when it installs uv), `~/.local/share/uv` (the tool environment and Python) and `~/.cache/uv`.
- A PATH line for `~/.local/bin` in the shell's startup files, only when that folder is not on the PATH yet. When the installer adds uv, uv's own installer from astral.sh writes these lines and can edit more than one file, such as `.zshenv`, `.zshrc` and `.profile`. On Windows it adds `~\.local\bin` to the user PATH instead.
- The MCP registration and skill folders of the agents it finds: `claude mcp add --scope user adengine` (or `~/.claude.json`), `~/.claude/skills/adengine-*`, `~/.codex/config.toml`, `~/.agents/skills/adengine-*`, `~/.cursor/mcp.json`, the VS Code user `mcp.json`, `~/.gemini/settings.json`, Windsurf's `mcp_config.json` and Claude Desktop's `claude_desktop_config.json`.

That registration is the product: Argus exists to give the user's agent these tools and skills. Each config file is backed up byte for byte to `~/.adengine/backups` before its first change.

## What it never does

- Use sudo or administrator rights.
- Ask for API keys or read them. The user connects services later, in the setup skill, without pasting keys into the chat.
- Install the unrelated `adengine` package from PyPI.
- Work around a sandbox. When it is blocked, it stops and prints the permission to ask for.
- Replace an `adengine` entry that Argus did not create, unless the user passes `--force` (the original is backed up first).

## Before you run it

### Permission and sandbox

The installer needs network access and permission to write in the user's home folder. Most agents run shell commands in a sandbox that blocks one or both, so run this one command outside the sandbox after the user approves it.

- Claude Code (terminal, VS Code, JetBrains or the desktop app): the Bash tool asks the user to approve the command. When the Claude Code sandbox is on, run this command without the sandbox after the user approves. The user can also run it themselves by typing it after `!` (bash mode).
- Codex (CLI, IDE extension or app): request escalated permissions for this command (`sandbox_permissions: "require_escalated"`, with a justification such as "Install Argus into your home folder; it needs network access") and wait for the approval. `codex exec` cannot ask for approval, so start it with `--sandbox danger-full-access`, or ask the user to paste the command into a terminal.
- Cursor: ask the user to approve "Run outside sandbox" for this command.
- VS Code with GitHub Copilot: ask the user to approve the terminal command. When terminal sandboxing is on, allow this command to run outside it.
- Gemini CLI: ask the user to approve the shell command. The install fails under `gemini --sandbox` (`-s`), so the user starts gemini without that option.
- Windsurf: ask the user to approve the command in Cascade.
- Any other agent: run it where it can reach the hosts below and write to the home folder, or ask the user to paste it into a terminal.

### Network hosts

- runargusapp.com: the release answer and the verified wheel.
- astral.sh: uv, when it is missing.
- github.com and objects.githubusercontent.com: uv and Python 3.12.
- pypi.org and files.pythonhosted.org: Python packages.
- Only for the optional follow-up steps: github.com and raw.githubusercontent.com (ffmpeg), and registry.npmjs.org and nodejs.org (video editor connections).

### curl or wget on macOS and Linux

The macOS and Linux installer needs one of curl or wget. It makes every download with the same one: curl when it is there, otherwise wget. macOS includes curl. Some minimal Linux systems, such as a fresh `ubuntu:24.04` container, leave out curl, and some of them have wget. Without curl, the curl forms in this guide print `curl: command not found`, and the agent form stops with exit code 127. Check with `command -v curl wget` first.

When only wget is there, use this form instead of the curl one:

```sh
f=$(mktemp) && wget -q -O "$f" https://runargusapp.com/install.sh && sh "$f"; rc=$?; rm -f "$f"; (exit $rc)
```

A person at a terminal can use `wget -qO- https://runargusapp.com/install.sh | sh`.

When the computer has neither, both forms stop with exit code 127 before anything changes. Ask the user to install curl with the system's package manager, for example `sudo apt-get install -y curl` on Debian or Ubuntu. The installer never uses sudo itself. An installer started some other way on such a computer stops the same way and reports `ARGUS_RESULT status=failed reason=no_curl_or_wget`.

### Time and timeout

The install usually takes 10 to 60 seconds, and up to 5 minutes on a slow connection. During long steps it prints a progress line every 15 seconds.

- Run it in the FOREGROUND with a timeout of 600000 ms.
- Do not run it in the background. In Claude Code, leave `run_in_background` off. A background run can outlive your session and hide the result.
- Do not stop it early. Wait for the last line, which starts with `ARGUS_RESULT`.
- If it is interrupted anyway, run the same command again. It resumes where it stopped.

### Preview first (optional)

`--plan` prints the hosts, folders and files the install would touch and the setup command it would run. It downloads and changes nothing.

```sh
f=$(mktemp) && curl -fsSL https://runargusapp.com/install.sh -o "$f" && sh "$f" --plan; rc=$?; rm -f "$f"; (exit $rc)
```

```powershell
& ([scriptblock]::Create((irm https://runargusapp.com/install.ps1))) --plan
```

## Install

macOS and Linux, in bash, zsh or sh. This form saves the installer to a private temporary file, so a failed download is a failed command, and it keeps the installer's exit code:

```sh
f=$(mktemp) && curl -fsSL https://runargusapp.com/install.sh -o "$f" && sh "$f"; rc=$?; rm -f "$f"; (exit $rc)
```

Do not pipe curl into sh from an agent. When the download fails, a pipe into sh still reports exit code 0. On a system without curl, run the wget form from "curl or wget on macOS and Linux" instead.

Windows, in PowerShell 5.1 or 7. A failed download is caught, and the final `exit` returns the installer's exit code:

```powershell
$LASTEXITCODE=1; try { & ([scriptblock]::Create((irm https://runargusapp.com/install.ps1))) } catch { [Console]::Error.WriteLine($_) }; exit $LASTEXITCODE
```

From a bash tool on Windows (such as Claude Code's), run the same line through PowerShell:

```sh
powershell -NoProfile -Command '$LASTEXITCODE=1; try { & ([scriptblock]::Create((irm https://runargusapp.com/install.ps1))) } catch { [Console]::Error.WriteLine($_) }; exit $LASTEXITCODE'
```

### Options

Put options after `sh "$f"` on macOS and Linux, or after the script block on Windows, for example `sh "$f" --no-editors`. These are the installer's own options:

- `--plan`: print what would happen, then stop. Nothing is downloaded or changed.
- `--core`: the core install only. This is the default inside an agent: ffmpeg and the video editor connections become optional follow-up steps.
- `--full`: the core install, then ffmpeg and the editor connections. This is the default in a terminal.
- `--no-editors`: never connect video editors.
- `--via-plugin`: the Argus Claude Code plugin connects Claude Code (see "Claude Code plugin" below).

Every other option goes to `adengine setup`:

- `--clients auto|none|<ids>`: which agents to register, for example `--clients claude-code,codex`. `auto`, the default, registers each of Claude Code, Codex, Claude Desktop, Cursor, VS Code, Gemini CLI and Windsurf that it finds. Agents that are written only when named: `qwen`, `kiro`, `amp`, `opencode`, `junie`, `warp` and `cline`.
- `--editor-mcps auto|none|resolve,capcut,premiere`: which video editor connections to set up.
- `--toolset auto|core|all`: the tool set to register (see "Tool limits").
- `--force`: replace an `adengine` entry that Argus did not create. The original is backed up and comes back on uninstall.

## Done when

1. The last line starts with `ARGUS_RESULT status=ok`, for example:

   ```text
   ARGUS_RESULT status=ok version=<version> ready=true restart_required=true harness=claude-code mode=core deferred=none first_prompt=/adengine-setup
   ```

   - `harness` is the agent the installer detected, and `first_prompt` is what the user types in it after the restart. A value with spaces is quoted, such as `first_prompt="use the adengine-setup skill"`.
   - `deferred` names the optional follow-up steps still to run (`ffmpeg`, `editors`), or `none`.
   - `ready=false` means a step is left for the user. The lines above `ARGUS_RESULT` say which one.
   - `plugin=claude-code` appears when the Claude Code plugin connects Claude Code.
   - A failed or blocked run ends with `ARGUS_RESULT status=failed` or `ARGUS_RESULT status=blocked`, plus `reason=` and `exit=`.

2. You ran the ffmpeg step if the installer printed one, and you asked the user before the editor step (see "Optional follow-up steps").

3. These checks pass. Use absolute paths, because `~/.local/bin` may not be on your shell's PATH yet:

   - `~/.local/bin/adengine doctor --json` lists every registration, and `next_steps` lists anything left. It exits 1 while a required step, such as ffmpeg, is still missing.
   - Claude Code: `claude mcp get adengine`, or `"$CLAUDE_CODE_EXECPATH" mcp get adengine` when `claude` is not on the PATH (the VS Code and JetBrains extensions).
   - Codex: `codex mcp list` shows `adengine`.
   - Gemini CLI: `gemini mcp list` shows `adengine`.
   - Any other agent: its config file has an `adengine` entry.

## Optional follow-up steps

Inside an agent the installer leaves two slower parts for later and prints each one as a command with absolute paths. Copy a command exactly as the installer printed it and run it as its own command, in the foreground, with a 600000 ms timeout and the same permission as the install, before the user restarts. Argus works without either one, and the user can run them later.

- ffmpeg, 5 to 60 seconds: `adengine doctor --fix --json` installs a verified ffmpeg of about 42 MB under `~/.adengine/bin`, which rendering needs. It runs only when no suitable ffmpeg is on the computer. Run it when the installer prints it.
- Video editors, 1 to 4 minutes: the command with `--editor-mcps auto` connects DaVinci Resolve, CapCut or Premiere Pro when one is installed. This step is an add-on. **Ask the user before you run it**, and run it only when they agree. The installer's list marks it "ask the user first" too. It changes more than the core install:
  - it downloads pinned editor servers and the runtimes they need;
  - it registers a server for each editor with Claude Code, Codex, Claude Desktop and Gemini CLI, the agents without a tool limit, and these editor servers can add hundreds of tools to each of them;
  - with Premiere Pro, it copies a bridge panel into the user's Adobe CEP extensions folder and turns on Adobe's PlayerDebugMode setting for the CEP version Premiere Pro uses, which lets any unsigned CEP panel load in Adobe apps on that version.

  `adengine uninstall` removes these and puts the previous PlayerDebugMode value back. You could ask: "Argus can also connect Premiere Pro, which adds its editor server and hundreds of tools to your agents. Do you want that now?"

## Restart, then the first prompt

An agent loads new MCP servers and skills only when a session starts. Always tell the user to restart, even when everything finished. Then give the first prompt for their agent. It starts the setup skill, which walks the user through their API keys and their video editor.

- Claude Code: restart Claude Code (type /exit, then run `claude --continue`; in VS Code or JetBrains, open a new Claude Code chat), then type `/adengine-setup`. With the Argus plugin, type `/adengine:adengine-setup` instead.
- Codex: restart Codex (quit and reopen it, or start a new chat in the IDE or app), then type `$adengine-setup`, or press `$` and pick it. Codex does not accept the slash form.
- Claude Desktop: quit Claude Desktop fully and reopen it, then pick the adengine-setup prompt from the `adengine` server's prompts.
- Cursor: restart the chat (in Cursor Settings > MCP, turn adengine on or refresh it, then start a new chat), then type `/adengine-setup`.
- VS Code: restart the chat (start a new chat, and start or trust the adengine server when VS Code asks), then type `/adengine-setup`.
- Gemini CLI: restart Gemini CLI (quit it and start gemini again), then say "use the adengine-setup skill".
- Windsurf: restart Windsurf (or refresh its MCP servers in the Cascade panel), then type `@adengine-setup`.

A message to the user can be as short as: "Argus is installed. Restart Claude Code (type /exit, then run claude --continue), then type /adengine-setup to connect your keys and your editor."

## Claude Code plugin

Claude Code 2.1.224 or later can add Argus as a plugin from the Argus marketplace. Update Claude Code first with `claude update` in a terminal, then type these in Claude Code, one at a time:

```text
/plugin marketplace add https://runargusapp.com/claude/marketplace.json
```

```text
/plugin install adengine@argus
```

The plugin adds the Argus skills and the `adengine` MCP server entry. It does not install the engine. Restart Claude Code so the plugin loads. Until the engine is installed, the plugin's server offers one tool, `install_argus`, which returns this command:

```sh
f=$(mktemp) && curl -fsSL https://runargusapp.com/install.sh -o "$f" && sh "$f" --via-plugin; rc=$?; rm -f "$f"; (exit $rc)
```

Run it like the install above. `--via-plugin` leaves Claude Code to the plugin, so its tools and skills are not listed twice, and still connects the user's other agents. After the install, restart Claude Code and type `/adengine:adengine-setup`, because plugin skills carry the plugin's name. A computer set up by the plain installer does not need the plugin.

On a Claude Code older than 2.1.224, `/plugin marketplace add` succeeds, and `/plugin install adengine@argus` then refuses with "This plugin uses a source type your Claude Code version does not support. Update Claude Code and try again." Run `claude update` in a terminal and install the plugin again, or use the installer above, which connects Claude Code without the plugin.

## Other agents

The installer registers Claude Code, Codex, Claude Desktop, Cursor, VS Code, Gemini CLI and Windsurf by itself when it finds them. For any other agent, install first, then print the entry for that agent and add it to the agent's MCP settings:

```sh
~/.local/bin/adengine mcp-config <agent>
```

- `adengine mcp-config --list` lists every agent it knows, with the config file, the key and the first prompt.
- `--link` prints a one-click install link for Cursor, VS Code and Goose, built for this computer's paths.
- `--format json|claude|vscode|toml|opencode|zed|goose|continue|amp` prints another shape, and `--json` prints everything as JSON, including where the entry goes.
- For an agent it does not list, use `adengine mcp-config generic --toolset core`.

Agents it knows beyond the automatic ones, each with the first prompt after its restart:

- Qwen Code (`qwen`): say "use the adengine-setup skill". `adengine setup --clients qwen` can also write it for you.
- Kiro (`kiro`): say "use the adengine-setup skill". `adengine setup --clients kiro` can also write it.
- Amp (`amp`): say "use the adengine-setup skill". `adengine setup --clients amp` can also write it.
- OpenCode (`opencode`): type `/adengine-setup`. `adengine setup --clients opencode` can also write it.
- Junie (`junie`): pick the adengine-setup prompt. `adengine setup --clients junie` can also write it.
- Warp (`warp`): type `/adengine-setup`. `adengine setup --clients warp` can also write it.
- Cline (`cline`): say "use the adengine-setup skill". `adengine setup --clients cline` can also write it.
- Goose (`goose`): say "use the adengine-setup skill".
- Continue (`continue`): pick the adengine-setup prompt.
- Zed (`zed`): pick the adengine-setup prompt.
- JetBrains AI Assistant (`jetbrains`): pick the adengine-setup prompt.
- Roo Code (`roo`): pick the adengine-setup prompt.

The entry always runs the absolute path of `adengine-mcp` with `serve`. `adengine-mcp serve` needs no other arguments and serves `~/.adengine/workspace`. For a client that reads `mcpServers`, it looks like this, with the user's own home folder in the path:

```json
{
  "mcpServers": {
    "adengine": {
      "command": "/Users/you/.local/bin/adengine-mcp",
      "args": ["serve", "--toolset", "core"]
    }
  }
}
```

VS Code's `mcp.json` uses the key `servers` with `"type": "stdio"`, and Codex uses a `[mcp_servers.adengine]` table in `~/.codex/config.toml`. `adengine mcp-config` prints the right shape for each.

## Tool limits

The full server has 226 tools. Some agents limit how many tools they load: Cursor keeps about 40 active, VS Code allows 128 per request and Windsurf 100 across all servers. For those, setup registers `--toolset core`: 25 tools, including `adengine_find_tools` and `adengine_call_tool`, which search and run every other tool, so nothing is out of reach. Claude Code, Codex, Claude Desktop and Gemini CLI get the full set. Pass `--toolset core` or `--toolset all` to choose yourself. Setup does not register video editor servers with agents that have a tool limit; `adengine mcp-config <agent> --server <editor>` prints one to add by hand.

## Troubleshooting

By exit code:

- `0`: installed, with `status=ok`. A step may be left for the user; the lines above `ARGUS_RESULT` say which.
- `1`: install error, with `status=failed reason=<reason>`. The line above it explains the problem, such as a checksum mismatch or a failed uv install. When setup itself failed, run `~/.local/bin/adengine doctor --json` and follow its `next_steps`.
- `2`: usage error, such as a mistyped option. Fix the option and run the command again.
- `10`: network blocked or unreachable, with `status=blocked`. Inside an agent this is the sandbox: the line on stderr names the permission to ask for. Get the user's approval and run the command outside the sandbox. In a terminal, check the internet connection and run it again.
- `11`: the home folder, or a folder setup needs, cannot be written, with `status=blocked`. Inside an agent this is also the sandbox; the fix is the same. Setup's own advice and a `Command:` line are printed on stderr.
- `127` from the macOS and Linux form: curl is not installed (or, from the wget form, wget is not). Use the other form, or ask the user to install curl (see "curl or wget on macOS and Linux").
- Another code, such as 6, 7 or 22 from curl, or 4, 5 or 8 from wget, from the macOS and Linux form: install.sh itself could not be downloaded. Treat it like `10`. On Windows a failed download ends with PowerShell's error and exit code 1.

By message:

- `Argus can't install inside <agent>'s sandbox`: run the command outside the sandbox after the user approves (see "Permission and sandbox").
- `Could not reach <host>`: the computer is offline, or a proxy blocks that host. The hosts are listed under "Network hosts".
- `already has an MCP server named "adengine" that Argus did not create`: another tool, or an older manual setup, owns that entry. Run `~/.local/bin/adengine setup --clients <agent> --force` to replace it; the original is backed up.
- `Resuming an interrupted install`: a normal re-run after an interruption.
- `Unknown skill: adengine-setup`, or no Argus tools in the agent: the agent has not restarted since the install. Restart it (see "Restart, then the first prompt").
- `Unrecognized command '/adengine-setup'` in Codex: type `$adengine-setup` instead.
- Codex says it has no Argus tools after the restart: Codex loads MCP tools on demand, when a task or `$adengine-setup` needs them, so a question such as "do you have the Argus tools?" can get a no even after a good install. `codex mcp list` is the check: it shows `adengine` when the install worked.
- `curl: command not found`: use the wget form, or ask the user to install curl (see "curl or wget on macOS and Linux").
- `ARGUS_RESULT status=failed reason=no_curl_or_wget`: the computer has neither curl nor wget. Ask the user to install curl.
- `ARGUS_RESULT status=failed reason=tls_unverified`: this wget cannot check TLS certificates, as with BusyBox's own TLS code, so the installer did not use its download. Ask the user to install curl.
- `This plugin uses a source type your Claude Code version does not support`: Claude Code is older than 2.1.224. Run `claude update` and install the plugin again, or use the installer.
- On Windows, a program that cannot be replaced during an update: quit the agent apps that use Argus, then run the command again.

## Uninstall

```sh
~/.local/bin/adengine uninstall --yes
```

It removes every agent registration and skill folder it recorded. A config file comes back from its backup byte for byte when nothing else changed it since; otherwise only the `adengine` entry is removed. The workspace in `~/.adengine/workspace` stays unless you add `--remove-workspace`. The program itself, uv and the downloaded Python stay too, and uninstall prints the commands that remove them: `uv tool uninstall adengine`, then delete `~/.adengine`.