software-mansion__argent/README.md

Argent

Argent has two HTTP surfaces:

• Tools server — Node/Express app (port 3001) that lists and invokes tools via a registry. Manages simulator lifecycle, debugger connections, and all tool logic.
• Simulator server — Native arm64 macOS binary (packages/native-devtools-ios/bin/) that runs one process per simulator. Handles device I/O: touch, keys, buttons, rotation, paste, scroll, MJPEG stream, screenshots, recording.

The tools server spawns simulator-server processes on demand. The UI and MCP bridge both talk to the tools server; the tools server talks to simulator-server instances.

Packages

Package	Path	Purpose
@argent/registry	packages/registry	Core library: dependency-aware service lifecycle, blueprints, tools, URNs. No HTTP or simulator logic.
@argent/tool-server	packages/tool-server	HTTP API over the registry (GET /tools, POST /tools/:name). Registers all blueprints and tools.
@argent/mcp	packages/mcp	MCP bridge — exposes all tools to AI assistants (Claude, Cursor) via Model Context Protocol.
@argent/skills	packages/skills	Markdown skill files that instruct AI agents when/how to use Argent tools.

Requirements

• macOS with Xcode installed (for xcrun simctl)
• Node.js 18+
• The simulator-server binary in packages/native-devtools-ios/bin/ (arm64 macOS)

Getting started

npm install

Run the tools server

npm run start

This builds the registry, then starts the tools server on port 3001.

npm run start:tool-server   # equivalent alias

Test it:

curl http://localhost:3001/tools                        # list tools
curl -X POST http://localhost:3001/tools/list-simulators \
  -H "Content-Type: application/json" -d '{}'           # invoke a tool

Installing in a project

The argent package is distributed via GitHub Packages under the @swmansion scope. Because the source repository is private, you must authenticate before installing.

Quick start (after completing auth setup):

npx @swmansion/argent install

This installs the package from GitHub Packages and configures MCP servers in .claude/mcp.json, .cursor/mcp.json, and copies skills, agents, and rules into your workspace.

VS Code launch configs

Config	What it does
Install Argent in Project	Prompts for a folder path, then builds, installs, and configures argent in that project.
Argent Agent Debug	Same as above but also opens the project in a new VS Code window and launches the tools server with debugger attached.
Tools Server	Runs the tool-server with ts-node on port 3001.
Tools Server (built)	Builds first, then runs the compiled tool-server.
UI (Chrome)	Opens the Vite UI in Chrome.
Full (Tools + UI)	Compound — starts both Tools Server and UI.

Building and testing

npm run build                          # tsc --build (all packages)
npm test -w @argent/registry           # registry unit tests (vitest)
npm test -w @argent/tool-server        # tool-server tests (vitest)

MCP package

npm run build -w @swmansion/argent   # compile + bundle into single CJS file
npm run pack:mcp                                  # build and create argent-<version>.tgz

Simulator server API

The simulator-server binary is normally spawned by the tools server. To run it standalone:

./packages/native-devtools-ios/bin/simulator-server ios --id <UDID>                          # defaults: port 3000, replay on, touch overlay on
./packages/native-devtools-ios/bin/simulator-server ios --id <UDID> --port 8080 --no-replay  # custom port, replay off

Flag	Env var	Default	Description
--port N	PORT	3000	Listen port
--replay / --no-replay	REPLAY	true	Rolling replay buffer
--show-touches / --no-show-touches	SHOW_TOUCHES	true	Touch pointer overlay

Quick reference (curl)

curl http://localhost:3000/simulators/running              # list running simulators

curl -X POST http://localhost:3000/sessions \
  -H "Content-Type: application/json" \
  -d '{"udid": "<UDID>", "token": "<JWT>"}'               # create session

curl -X POST http://localhost:3000/sessions/<id>/screenshot  # screenshot (Pro)

curl -X POST http://localhost:3000/sessions/<id>/input/touch \
  -H "Content-Type: application/json" \
  -d '{"type":"Down","points":[{"x":0.5,"y":0.5}]}'       # tap (normalized 0-1)

Further reading

See docs/reference.md for a detailed breakdown of the registry, blueprints, services, tools, and how they all connect.

License

The "Argent" project utilizes a mixed licensing model to provide open-source accessibility while protecting specific proprietary binary components.

Source Code

The vast majority of the source code (business logic, scripts, interfaces, etc.) is released under the Apache License 2.0. You can find the full text of the license in the <LICENSE.TXT> file. You are free to use, modify, and distribute this portion of the project in accordance with the terms of the Apache 2.0 license.

Proprietary Binary Components

Certain elements of the project are provided exclusively as compiled binary files (typically located in the /bin or /libs directories).

• Files:
  • packages/native-devtools-ios/bin/simulator-server
  • packages/native-devtools-ios/dylibs/libInjectionBootstrap.dylib
  • packages/native-devtools-ios/dylibs/libKeyboardPatch.dylib
  • packages/native-devtools-ios/dylibs/libNativeDevtoolsIos.dylib
• Status: These files are NOT Open Source software.
• Terms: They are the intellectual property of Software Mansion S.A. and are licensed solely for use in conjunction with this project. Decompiling, reverse engineering, disassembling, or redistributing these binary files outside the scope of this project without explicit written permission is strictly prohibited.

By using or contributing to this project, you acknowledge and agree to this mixed licensing structure.