How software-mansion/argent works
1. Overall shape
This is a TypeScript monorepo for a local, agent-facing toolkit. The product is designed to run entirely on the user’s machine and connect to an AI assistant through MCP over stdio, not through a hosted backend.
2. Primary entrypoint: packages/argent
The published argent package is the top-level CLI distribution. It owns the user-facing commands such as init, update, remove, and mcp, and it also contains packaging glue for the bundled runtime assets and native binaries.
3. CLI/runtime lifecycle
packages/argent-cli and packages/argent/src handle argument parsing, process startup, and fatal error handling for the local agent runtime. This is the boundary where a shell command turns into a long-lived local service or one-off installer action.
4. Workspace onboarding: packages/argent-installer
The installer is responsible for modifying the user’s project and editor config. It detects supported editors, writes MCP configuration files, copies Argent skills/rules/agent definitions into the workspace, and supports uninstall/update flows. This package is the main bridge between Argent and the user’s repository.
5. Agent protocol boundary: packages/argent-mcp
This package is the MCP server exposed to the AI assistant. It maps MCP requests into Argent tool invocations, handles content extraction, and can trigger automatic screenshots. Architecturally, it is the narrow protocol layer between the assistant and the rest of the system.
6. Core execution engine: packages/tool-server
The largest subsystem is the local tool server, which contains the actual capabilities. It is organized by domain:
- device management
- app launch/restart/reinstall
- gestures, keyboard, paste, buttons
- screenshots and screen description
- debugger and Metro integration
- network inspection
- profiler workflows
- simulator control
- workspace and update utilities
7. Platform boundaries inside the tool server
Many tools are split by platform, especially Android vs iOS. The Android side relies on adb, emulator control, and UIAutomator parsing. The iOS side relies on Xcode-related tooling, Instruments, Accessibility/native adapters, and proprietary devtools binaries. Cross-platform tools route through shared abstractions in src/utils.
8. Profiling and diagnostics pipeline
Profiling is a major subsystem, not just a single command. There are separate pipelines for React Native profiling and iOS Instruments profiling, each with multi-step processing stages that correlate events, enrich data, resolve source locations, and produce human-readable summaries. The runtime outputs are diagnostic reports rather than raw traces alone.
9. Debugging and app introspection
Debugger-related tools connect to Metro/Chrome DevTools Protocol, inspect component trees, evaluate code, inspect elements, and collect logs. Separate “describe” tools build structured UI trees from Android and iOS accessibility/native sources, which is how Argent can reason about the current screen state.
10. Shared helpers and registries
packages/registry provides shared registry/event/schema utilities, including JSON-schema conversion and typed error/event handling. packages/argent-tools-client is a small client/launcher layer used to start or talk to the tool server from another process boundary.
11. Skills as prompt/runtime content
packages/skills is content-heavy rather than runtime-heavy: markdown skills, rules, and agent guidance that are installed into the workspace. This is an important architectural boundary because it shapes the assistant’s behavior without being part of the tool execution path.
12. Native/proprietary assets
The repo depends on bundled local binaries for things like simulator services, AX service, and iOS native devtools support. These are shipped as private assets and are consumed by the tool server at runtime, making native OS integration a first-class part of the architecture.
13. Data flow summary
The main flow is: CLI install/configure → MCP connection → tool server action → local device/simulator/OS tooling → structured result back to the assistant. Outputs can include screenshots, logs, device state, profiler summaries, and UI descriptions, all produced locally.
14. Operational boundary
There is no cloud control plane in the runtime path. The architecture is intentionally local-first: workspace config is written on disk, the assistant talks over MCP stdio, and the tool server reaches only local simulators/devices, Metro, Xcode/Instruments, and adb-based Android tooling.
Main entry points: tool-server Tool server · argent argent · argent-installer Installer · argent-mcp MCP server
Components 16
CLI & packaging
User-facing commands and distribution glue
- argent · Top-level CLI distribution and packaging entrypoint
packages/argent - CLI runtime · Argument parsing, startup, and fatal error handling
packages/argent/src - Installer · Writes MCP config, installs skills, and handles update/uninstall flows
packages/argent-installer
Protocol bridge
MCP-facing boundary and process launcher
- MCP server · Exposes Argent capabilities over MCP and maps requests to tools
packages/argent-mcp - Tools client · Starts or connects to the local tool server from another process
packages/argent-tools-client
Local runtime
Core tool execution and device control
- Tool server · Main capability host for device, app, debugger, profiler, and workspace tools
packages/tool-server - Device tools · Boots devices and manages app launch, restart, reinstall, gestures, keyboard, and paste
packages/tool-server/src/tools - Describe · Builds structured UI trees from Android and iOS accessibility/native sources
packages/tool-server/src/tools/describe - Debugger · Connects to Metro and DevTools for component trees, evaluation, inspection, and logs
packages/tool-server/src/tools/debugger - Profiler · Runs React Native and iOS profiling workflows and produces readable reports
packages/tool-server/src/tools/profiler - Simulator · Manages simulator server lifecycle and related local runtime processes
packages/tool-server/src/tools/simulator - Network · Captures and queries request and log data from the local app environment
packages/tool-server/src/tools/network
Content & shared
Installed skills and shared schemas/utilities
Native assets
Bundled local binaries and platform-specific support
- iOS native · Bundled iOS-native devtools and profiler support assets
packages/native-devtools-ios - Native binaries · Private local binaries and shipped runtime assets consumed at execution time
assets
Connections 20
- argent → CLI runtime: starts · CLI package hands off to runtime entrypoint
- argent → Installer: exposes · Distribution includes install, update, and remove commands
- argent → MCP server: ships · Package provides the MCP-facing runtime entry
- argent → Native binaries: bundles · Packaging layer collects local binaries and runtime assets
- CLI runtime → Tools client: launches · CLI runtime can start the local tool server client boundary
- Installer → Skills: installs · Installer copies skills, rules, and guidance into the workspace
- Installer → MCP server: configures · Installer writes MCP configuration for the assistant connection
- MCP server → Tools client: invokes · MCP requests are translated into tool-server calls
- Tools client → Tool server: connects · Launcher/client boundary reaches the local engine process
- Tool server → Device tools: runs · Core engine executes local device and app operations
- Tool server → Describe: runs · Engine produces structured screen descriptions
- Tool server → Debugger: runs · Engine exposes debugger and inspection capabilities
- Tool server → Profiler: runs · Engine executes profiling workflows and report generation
- Tool server → Simulator: controls · Engine manages simulator-side processes and lifecycle
- Tool server → Network: captures · Engine collects and queries local network diagnostics
- Tool server → Registry: uses · Tool server relies on shared schemas, events, and error handling
- Profiler → iOS native: depends on · iOS profiling pipeline consumes native devtools support
- Tool server → Native binaries: uses · Runtime depends on shipped native binaries and assets
- MCP server → Registry: uses · Protocol layer uses shared schema and error utilities
- Installer → Registry: uses · Installer shares registry and schema utilities