Installation
Prerequisites
- Node.js 22.18 or later, but not 23.0 to 23.7
- iOS / tvOS: macOS with Xcode installed. Apple TV uses tvOS simulators, and Xcode downloads the tvOS runtime on demand.
- Android / Android TV: Android SDK Platform Tools (
adb), plus the Android Emulator package to boot AVDs from Argent. Argent finds the SDK onPATH, in$ANDROID_HOME, or in the default SDK folder. Theandroid.sdkRootconfig key sets another location. Create AVDs via Android Studio oravdmanager. - Fire TV (Vega): the Vega SDK (
vegaCLI) onPATH, plus Android SDK Platform Tools (adb) onPATH. Most Vega tools, including UI inspection and screenshots, run overadb. - HarmonyOS: DevEco Studio, which ships
hdc(the device connector) and theEmulatormanager. Argent looks for both in$DEVECO_STUDIO_HOMEfirst, then in/Applications/DevEco-Studio.appon macOS. Argent also findshdconPATH, for hosts that installed the OpenHarmony command-line tools without the IDE. A phone needs onlyhdc. Runargent enable harmonyosto turn on HarmonyOS support. - Electron / Chromium: nothing extra to control an already running app. Launch it with
--remote-debugging-port, or let Argent spawn your Electron app for you. - Mac apps: macOS 14.4 or later and a build of your app. See Mac apps.
- TypeScript scripts in e2e tests: a Node.js build that includes TypeScript support. The
nodejspackage of Debian and of Ubuntu does not include it. See TypeScript scripts.
Run init in your project
npx @swmansion/argent@latest init
In a pnpm project, where npm's devEngines check may refuse to run npx:
pnpm dlx @swmansion/argent@latest init
The argent package on npm is a short alias for @swmansion/argent. It runs the same @swmansion/argent version:
npx argent@latest init
The alias is only for npx. To install Argent globally, install @swmansion/argent.
The installation wizard:
- installs
@swmansion/argentglobally, - detects your editor and registers the MCP server,
- copies skills into your workspace.
The MCP server gives the agent its usage guidance in the server instructions. When the wizard configures the MCP server globally, it writes no rule file. When the wizard configures the MCP server for one project, it also writes a short rule into that project. This rule tells the agent what to do when the project uses Argent but Argent is not installed.
Manual install
npm install -g @swmansion/argent
argent init
Install from a GitHub release
Every release on GitHub carries the package tarball as an asset, for example swmansion-argent-0.34.0.tgz. It is the same file npm serves. Download it and install it globally:
npm install -g ./swmansion-argent-0.34.0.tgz
argent init
Argent's own dependencies still come from your configured npm registry.
Share Argent with your team
By default Argent installs globally. To version Argent with your repo, so every teammate gets the same setup on npm install, choose the local mode:
npx @swmansion/argent@latest init --local
This adds @swmansion/argent to your project's devDependencies and writes MCP configs that launch the project-local copy. Commit package.json and your lockfile, the generated MCP config (.mcp.json, .cursor/mcp.json, and so on), .argent/install.json, and the skills and rules files. Teammates then run npm install.
Pass --global to force the default mode in scripts. --local and --global are mutually exclusive. A non-interactive (--yes) run defaults to global unless the project already opted into local mode.
Add --no-telemetry to also commit a telemetry opt-out for the repository. Local mode then writes .argent/config.json with telemetry.enabled: false, which turns telemetry off on every clone. See Telemetry and privacy.
In local mode the committed MCP config runs the project-local copy, so the bare argent command is not on teammates' PATH. Note that npm install builds Argent's native dependencies (tree-sitter) on each machine. These are prebuilt for macOS, Linux x64 and Windows x64; other targets compile from source and need a C/C++ toolchain.
macOS hosts after an Xcode update
After you install or update Xcode, Xcode must install its system components. Until then, a simctl or devicectl call can start that install. The install waits for an administrator password, also when nobody sees the prompt.
Argent reads Xcode's files to find if a simctl or devicectl call starts the install.
If a simctl call starts the install:
- Argent does not look for booted simulators in the background.
list-devicesdoes not show local iOS simulators. Itshintfield gives the reason to the agent.- The tools that need
simctlfail. Most of them return an error that gives the same reason to the agent.
Argent reads the type of a simulator with simctl. Argent must know the type to find an Apple TV simulator or a foldable iOS simulator. Thus, the tools that send input to a simulator or capture its screen also fail if Argent does not know its type yet. This occurs, for example, when Argent starts after the Xcode update.
If a devicectl call starts the install:
list-devicesdoes not show physical iPhones. Itshintfield gives the reason to the agent.- The tools that need
devicectlfail. Most of them return an error that gives the same reason to the agent. - A tool that only talks to the runner on the iPhone keeps working while the runner is up.
Argent stops only its own calls. An xcrun simctl or xcrun devicectl command that the agent or you run still starts the install. Commands that call simctl or devicectl, for example npx react-native run-ios, also start it.
The hint field and the error name the Xcode that must install its components. If you have more than one Xcode, use the Xcode that Argent names.
To install the components, do one of these steps:
- Open that Xcode and let it install the components.
- Run the
xcodebuildof that Xcode withsudo, for examplesudo /Applications/Xcode.app/Contents/Developer/usr/bin/xcodebuild -runFirstLaunch.
Argent finds the installed components at the next tool call. You do not need to restart Argent.
Linux hosts running Android emulators
Argent runs Android emulators on Linux, but a few host-side knobs matter:
-
KVM access. Without
/dev/kvmthe emulator falls back to slow software emulation. Enable virtualization in BIOS/UEFI and add your user to thekvmgroup:sudo usermod -aG kvm "$USER"
# log out and back in so the new group takes effect -
glibc version. The gesture tools,
screenshot,rotateandpastestart the bundledsimulator-serverbinary. This binary needs glibc 2.39 or newer, for example Ubuntu 24.04 or Debian 13. On an older host, the binary does not start. These tools then fail withversion `GLIBC_2.39' not found. Runldd --versionto see the glibc version of the host. -
GPU mode. Argent picks
-gpu swiftshaderon Linux for universal compatibility. Override it withARGENT_EMULATOR_GPU_MODE=hostif you have verified that hardware GL works on your machine. -
System image. Prefer the
defaultorgoogle_apisvariants ofx86_64images. Always pickx86_64on Intel and AMD hosts, since ARM images run through QEMU translation and are dramatically slower. -
AVD resources. Stock 2 GB / 4 vCPU AVDs can be CPU-starved by a concurrent Gradle build. Bump
hw.ramSize,hw.cpu.ncoreandvm.heapSizein~/.android/avd/<name>.avd/config.ini. -
Headless mode. Export
ARGENT_EMULATOR_NO_WINDOW=1before starting the tool-server in CI, containers or Wayland-only sessions.