Ignacy Łątka
3ce2d5c13f
Action enumeration
- MIN_TAP_AREA was an area floor, which is the wrong shape for what it
documented: a 44x44pt HIG-minimum button is 0.1 x 0.046 = 0.0046 of an
iPhone 16 Pro Max and was dropped, while a full-width 6pt divider
(1.0 x 0.006) was kept. Replaced with a per-axis minimum.
- The destructive-action guard ignored `identifier`, so an icon-only control
whose only tell is com.app:id/logout_button was tapped. Include it, and
split identity separators first ("_" is a word char, so \blogout\b does not
match logout_button).
- deriveMapSelector skipped the `value` fallback its twin deriveSelector
documents, so a value-only element replayed by frame.
- isTappableIosRole matched cell/menuitem/tab and guarded `table`, none of
which the iOS adapters can emit. Removed the dead branches, corrected the
doc, and recorded the real consequence (a trait-less row arrives as
AXGroup and is not enumerated) as a deliberate v1 trade-off.
Crawler
- The deep-link re-root was strictly weaker than its tap-path twin: gated on
the landed screen's owed actions and never re-propagating depth, so a deep
link onto a fully-explored hub left depth-capped descendants dead. Re-root
and re-propagate regardless of the hub's own state.
- Forward taps used the frame recorded at first enumeration instead of the
selector stored beside it. A reordered list re-keys identically (screenKey
ignores labels, buckets frames to 5%), so the tap hit whatever now occupied
that rectangle and the edge got one row's label with another's destination.
- isTargetForeground and screenshot were awaited unguarded although the
CrawlDriver contract says every method may reject.
- A failed launch no longer proceeds on an unverified tree: iOS describe reads
whichever app is frontmost, so a mistyped bundle id crawled a stranger's app
and reported completed, while the error naming that exact cause could never
fire.
Tool and contract
- Reject tvOS / Android TV up front (both pass the platform capability gate)
via UnsupportedOperationError, as sibling screen-driving tools do.
- Correct the MapCrawlState tool-result-shape doc, MapSelector.label's
"(exact)" claim, and the stats.restarts definition.
- State the maxActionsPerScreen / maxDepth caps; measure maxDepth from each
screen's own entry; reject empty deepLinks entries.
UI
- De-overlap convergence is tested against a sub-pixel tolerance rather than
exact zero. Resolving a pair drives it to exact contact, where float residue
leaves penetration marginally positive, so the early break could never fire:
re-solving a settled 200-node layout spent 1200 of 1200 passes, now 1, with
0 card-footprint intersections either way.
- releaseAllInput() on tab switch: the key gate drops keyup too, so switching
tabs with a key held stranded it down on the device.
- Escape on the Map tab also reached Lens's handler and tore down an
in-progress comment; handle in capture phase and confine to Map.
- mapEdgePathD emitted NaN control points for coincident node centres, so the
browser discarded the path and the edge silently vanished.
- Correct the determinism comment: positions are deterministic per revision
sequence, not per graph.
Docs
- Add `argent map` to the CLI Reference; give the MAP_* failure codes the
group comment every neighbouring group has.
17 KiB
Argent is an agentic toolkit that gives your AI assistant direct access to iOS Simulators, Android emulators and physical devices, TVs (Apple TV, Android TV, Fire TV) and Electron/Chromium desktop and web apps. Ask it to tap a button, run a profiler or reproduce an issue manually - all from within your CLI, without switching context.
npx @swmansion/argent@latest init
# or, in a pnpm project (where npm's devEngines check may refuse to run npx):
pnpm dlx @swmansion/argent@latest init
Supported platforms
Argent drives a growing set of targets through a single toolkit, each with the right interaction model - touch, remote or mouse:
| Platform | Targets | Interaction |
|---|---|---|
| iOS | Simulators | Touch / gesture |
| Android | Emulators (AVDs) and physical devices over adb | Touch / gesture |
| TV | Apple TV (tvOS), Android TV / Google TV, Amazon Fire TV (Vega) | D-pad / remote |
| Desktop & web | Electron and Chromium apps (incl. React Native Web / Expo web) over CDP | Mouse / keyboard |
Capabilities
- Autonomous mobile, TV and desktop development - Allow your agent to work with iOS, Android, TV and Electron/web apps on its own - let it build, open, interact with the app and debug it. Ask for reproducing issues, testing features manually, profiling your app and much more, without ever interrupting your work.
- UI interaction - Give your agent the full control toolkit - tapping, swiping, pinching, typing, gestures and hardware buttons on mobile; the directional remote on TV; mouse, scroll and drag on desktop/web. Let it navigate your app exactly as a user would, without lifting a finger.
- Record & replay flows - Capture a sequence of interactions once and let your agent replay it deterministically, so manual repros and smoke tests become repeatable.
- Visual regression - Diff two screenshots (or a saved baseline against a live capture) with OCR- and font-aware comparison to catch unintended UI changes.
- Profiling with batteries included - Argent can perform and analyze React Native (Hermes), React DevTools and native (Xcode Instruments / Android Perfetto) profiling sessions - down to fiber renders, CPU hotspots and cross-correlated commit-vs-hang reports. Get comprehensive summaries and ask to optimise your app where you find fit.
- Debugging and diagnostics - Let your agent inspect logs, capture network traffic (JS
fetchand native), evaluate JS in the running app, walk the native UIKit and React component trees, and reproduce failing states - so you can jump straight to the fix. - Desktop & web control - For Electron and Chromium apps your agent can drive tabs, read and write cookies and storage, walk the DOM and inspect network over the Chrome DevTools Protocol.
- React Native out of the box - Argent works with React Native apps natively, so your agent can build, launch, and iterate on your RN project the same way it would any native app - no extra setup required.
Tip: Once installed, ask your assistant "What can Argent do?" - it will walk you through all capabilities available.
Installation
Prerequisites
- Node.js 20.11 or later
- For iOS / tvOS: macOS with Xcode installed (Apple TV uses tvOS simulators — Xcode downloads the tvOS runtime on demand)
- For Android / Android TV: Android SDK Platform Tools (
adb) onPATH, and the Android Emulator package if you want to boot AVDs from Argent. Create AVDs via Android Studio oravdmanager. - For Fire TV (Vega): the Vega SDK (
vegaCLI) onPATH - For Electron / Chromium: nothing extra to control an already-running app - just launch it with
--remote-debugging-port, or let Argent spawn your Electron app for you
Linux host: extra prerequisites for Android emulators
Argent runs Android emulators on Linux but the default install can be slow if a few host-side knobs aren't right. Cover these once and the experience matches macOS:
-
KVM access. The emulator falls back to slow software emulation (TCG) without
/dev/kvm. Make sure virtualization is enabled in BIOS/UEFI (vmxfor Intel,svmfor AMD in/proc/cpuinfo) and that your user can read/write/dev/kvm— on most distros that means joining thekvmgroup:sudo usermod -aG kvm "$USER" # log out and back in so the new group takes effect -
GPU mode (
-gpu swiftshaderon Linux, override available). The Android emulator's Linux GPU story is messy:-gpu autofrequently resolves to lavapipe (slow software Vulkan via host libvulkan, ~10× cold-boot regression on flagship hardware), and-gpu hostsilently produces a corrupted or black emulator window on hosts with non-trivial GL stacks — dual-GPU / Optimus laptops, NVIDIA + Mesa coexistence via libglvnd, Wayland sessions on hybrid graphics, headless / containerized hosts. The failure mode is invisible to argent's framebuffer-based screenshot tool, so an agent reports success while the developer sees a black window.Argent picks
-gpu swiftshaderon Linux for universal compatibility: it sidesteps the host GL stack entirely and renders via the emulator's bundled SwiftShader. On modern multi-core machines this is indistinguishably smooth from hardware-accelerated-gpu host(and far faster than lavapipe).Override with the
ARGENT_EMULATOR_GPU_MODEenv var if you've verified-gpu hostworks on your machine (typical single-GPU Mesa box with a healthy X session):ARGENT_EMULATOR_GPU_MODE=host argent ...Argent's boot-device preflight prints a warning if
/dev/kvmisn't usable — the condition that causes a 10–50× TCG-vs-KVM slowdown. -
System image. Prefer the
defaultorgoogle_apisvariants ofx86_64system images for headless agent workflows;google_apis_playstoreadds noticeable boot-time CPU churn from Play services. Always pickx86_64on Intel/AMD hosts — ARM images run via QEMU translation and are dramatically slower. -
AVD config. AVDs created via
avdmanager create avddefault tohw.gpu.enabled=no. Argent overrides this with an explicit-gpuarg at launch (so the on-disk config doesn't need editing). For the smoothest experience under heavy native builds (gradle compilations alongside the AVD), bump the AVD's RAM and CPU count — edit~/.android/avd/<name>.avd/config.ini:hw.ramSize = 8192 hw.cpu.ncore = 6 vm.heapSize = 512Stock 2 GB / 4 vCPU AVDs can be CPU-starved into wedged-system_server states by a concurrent gradle/Kotlin compile.
-
Headless / CI mode (
ARGENT_EMULATOR_NO_WINDOW=1). Argent shows the emulator window by default so a local developer can see the AVD UI. In a headless context — CI runner, container, or a Wayland-only session where the emulator's bundled Qt has nowaylandplatform plugin and SIGABRTs on the crash-consent dialog — opt out by exportingARGENT_EMULATOR_NO_WINDOW=1before starting the tool-server. This appends-no-windowto the spawn args, selectingqemu-system-x86_64-headlesswhich doesn't need a Qt window. Argent's screencap-based screenshot tool reads the in-memory framebuffer correctly without a visible window.
Run init in your project
From your project root:
npx @swmansion/argent@latest init
# or, in a pnpm project (where npm's devEngines check may refuse to run npx):
pnpm dlx @swmansion/argent@latest init
This command triggers an installation wizard which:
- Installs
@swmansion/argentglobally - Detects your editor and registers the MCP server
- Copies skills, rules, and agent definitions into your workspace
Prefer a manual install?
npm install -g @swmansion/argent
argent init
Share Argent with your team (committable install)
By default Argent installs globally. To version Argent with your repo so every
teammate gets the same setup on npm install — no per-developer global install, no
argent init — choose the local mode:
npx @swmansion/argent@latest init --local
# or, in a pnpm project:
pnpm dlx @swmansion/argent@latest init --local
Note: in a freshly
pnpm init-ed project,npxitself may refuse to run (npm'sdevEnginescheck) — use thepnpm dlxform there.
This adds @swmansion/argent to your project's devDependencies and writes MCP
configs that launch the project-local copy (node node_modules/@swmansion/argent/dist/cli.js mcp).
Commit package.json + your lockfile, the generated MCP config (.mcp.json,
.cursor/mcp.json, …), .argent/install.json, and the skills/rules/agents files.
Teammates then just 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 (a committed .argent/install.json, or
@swmansion/argent declared in the project's own package.json).
In local mode the committed MCP config runs the project-local copy, so the bare
argentcommand is not on teammates'PATH. Note thatnpm installbuilds Argent's native deps (tree-sitter) on each machine — prebuilt for macOS, Linux x64, and Windows x64; other targets (Linux arm64, Windows arm) compile from source and need a C/C++ toolchain.
CLI Reference
| Command | Description |
|---|---|
argent init |
Install and configure MCP in the current workspace (--global default, --local for a committable devDependency) |
argent install |
Alias for init command |
argent update |
Pull the latest version and refresh workspace configuration (acts on the present install — both when a global install and a project devDependency coexist; --global/--local select explicitly) |
argent uninstall |
Unregister the MCP server and uninstall the package (--global/--local choose which install — and its configs — is removed; non-interactive runs never remove a coexisting global install) |
argent remove |
Alias for uninstall command |
argent mcp |
Start MCP server instance, used internally by agent |
argent tools |
List tools exposed by the tool-server (describe <name> for details) |
argent run |
Invoke a tool by name |
argent server |
Manage the shared tool-server: start / status / stop / logs |
argent lens |
Open Argent Lens bound to a fresh coding-agent session — Claude by default, --agent selects codex/gemini/opencode/cursor (macOS; behind the argent-lens flag — run argent enable argent-lens first) |
argent map |
Crawl an app into a graph of its reachable screens and render it live in the preview window's Map tab (behind the argent-map flag — run argent enable argent-map first) |
argent link |
Route client requests to a remote tool-server |
argent unlink |
Remove the persisted remote tool-server link |
argent enable |
Enable a predefined feature flag (--scope project for project-local) |
argent disable |
Disable a feature flag (--scope project for project-local) |
argent flags |
List available feature flags and their state |
argent telemetry |
Manage telemetry: status / enable / disable |
Supported Editors
argent init auto-detects and configures MCP for:
| Editor | Config location |
|---|---|
| Claude Code | .mcp.json (project) or ~/.claude.json (global) |
| Cursor | .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) |
| VS Code | .vscode/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json (global) |
| Zed | .zed/settings.json (project) or ~/.config/zed/settings.json (global) |
| Gemini CLI | .gemini/settings.json |
| Codex CLI | .codex/config.toml (project) or ~/.codex/config.toml (global) |
| Hermes | ~/.hermes/config.yaml (global) |
| opencode | opencode.json (project) or ~/.config/opencode/opencode.json (global) |
| Kiro | .kiro/settings/mcp.json (project) or ~/.kiro/settings/mcp.json (global) |
Privacy
Argent collects opt-out usage and diagnostic telemetry to help us prioritise features and fix what breaks.
You can opt out at any time:
argent telemetry disable # check status with: argent telemetry status
For the full details — see the Argent Privacy Notice (Telemetry).
License
Argent uses a mixed licensing model.
Source code is released under the Apache License 2.0.
Proprietary binaries (the per-platform bin/<platform>/simulator-server and bin/darwin/ax-service executables and the .dylib files in native-devtools-ios) are the intellectual property of Software Mansion S.A. and are licensed solely for use within this project. Decompiling, reverse-engineering, or redistributing them without explicit written permission is prohibited.
By using Argent, you acknowledge and agree to this structure. See LICENSE for full details.
Argent is created by Software Mansion
Since 2012 Software Mansion is a software agency with experience in building web and mobile apps. We are Core React Native Contributors and experts in dealing with all kinds of React Native issues. We can help you build your next dream product – Hire us.