Agent install guide

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

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

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

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.

Network hosts

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:

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.

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.

f=$(mktemp) && curl -fsSL https://runargusapp.com/install.sh -o "$f" && sh "$f" --plan; rc=$?; rm -f "$f"; (exit $rc)
& ([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:

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:

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

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:

Every other option goes to adengine setup:

Done when

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

    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.

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.

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:

/plugin marketplace add https://runargusapp.com/claude/marketplace.json
/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:

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:

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

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

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:

{
  "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:

By message:

Uninstall

~/.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.