# software-mansion/argent architecture

> Architecture diagram of the GitHub repository software-mansion/argent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/software-mansion/argent
- Repository: https://github.com/software-mansion/argent

## Overview

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: [`packages/tool-server`](https://github.com/software-mansion/argent/tree/main/packages/tool-server) (Tool server), [`packages/argent`](https://github.com/software-mansion/argent/tree/main/packages/argent) (argent), [`packages/argent-installer`](https://github.com/software-mansion/argent/tree/main/packages/argent-installer) (Installer), [`packages/argent-mcp`](https://github.com/software-mansion/argent/tree/main/packages/argent-mcp) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli["CLI & packaging"]
  node_node_argent["argent"]
  node_node_argent_cli["CLI runtime"]
  node_node_installer["Installer<br/>workspace setup"]
end

subgraph group_group_protocol["Protocol bridge"]
  node_node_mcp["MCP server<br/>protocol bridge"]
  node_node_tools_client["Tools client<br/>launcher client"]
end

subgraph group_group_runtime["Local runtime"]
  node_node_tool_server["Tool server<br/>local engine"]
  node_node_device_tools["Device tools<br/>device control"]
  node_node_describe["Describe<br/>ui introspection"]
  node_node_debugger["Debugger<br/>metro/cdp"]
  node_node_profiler["Profiler<br/>diagnostics"]
  node_node_simulator["Simulator<br/>platform control"]
  node_node_network["Network<br/>inspection"]
end

subgraph group_group_content["Content & shared"]
  node_node_registry["Registry<br/>schemas/events"]
  node_node_skills["Skills<br/>prompt content"]
end

subgraph group_group_native["Native assets"]
  node_node_native_ios["iOS native<br/>native assets"]
  node_node_assets[("Native binaries<br/>bundled assets")]
end

node_node_argent -->|"starts"| node_node_argent_cli
node_node_argent -->|"exposes"| node_node_installer
node_node_argent -->|"ships"| node_node_mcp
node_node_argent -->|"bundles"| node_node_assets
node_node_argent_cli -->|"launches"| node_node_tools_client
node_node_installer -->|"installs"| node_node_skills
node_node_installer -->|"configures"| node_node_mcp
node_node_mcp -->|"invokes"| node_node_tools_client
node_node_tools_client -->|"connects"| node_node_tool_server
node_node_tool_server -->|"runs"| node_node_device_tools
node_node_tool_server -->|"runs"| node_node_describe
node_node_tool_server -->|"runs"| node_node_debugger
node_node_tool_server -->|"runs"| node_node_profiler
node_node_tool_server -->|"controls"| node_node_simulator
node_node_tool_server -->|"captures"| node_node_network
node_node_tool_server -->|"uses"| node_node_registry
node_node_profiler -->|"depends on"| node_node_native_ios
node_node_tool_server -->|"uses"| node_node_assets
node_node_mcp -->|"uses"| node_node_registry
node_node_installer -->|"uses"| node_node_registry

click node_node_argent "https://github.com/software-mansion/argent/tree/main/packages/argent"
click node_node_argent_cli "https://github.com/software-mansion/argent/tree/main/packages/argent/src"
click node_node_installer "https://github.com/software-mansion/argent/tree/main/packages/argent-installer"
click node_node_mcp "https://github.com/software-mansion/argent/tree/main/packages/argent-mcp"
click node_node_tools_client "https://github.com/software-mansion/argent/tree/main/packages/argent-tools-client"
click node_node_tool_server "https://github.com/software-mansion/argent/tree/main/packages/tool-server"
click node_node_device_tools "https://github.com/software-mansion/argent/tree/main/packages/tool-server/src/tools"
click node_node_describe "https://github.com/software-mansion/argent/tree/main/packages/tool-server/src/tools/describe"
click node_node_debugger "https://github.com/software-mansion/argent/tree/main/packages/tool-server/src/tools/debugger"
click node_node_profiler "https://github.com/software-mansion/argent/tree/main/packages/tool-server/src/tools/profiler"
click node_node_simulator "https://github.com/software-mansion/argent/tree/main/packages/tool-server/src/tools/simulator"
click node_node_network "https://github.com/software-mansion/argent/tree/main/packages/tool-server/src/tools/network"
click node_node_registry "https://github.com/software-mansion/argent/tree/main/packages/registry"
click node_node_skills "https://github.com/software-mansion/argent/tree/main/packages/skills"
click node_node_native_ios "https://github.com/software-mansion/argent/tree/main/packages/native-devtools-ios"
click node_node_assets "https://github.com/software-mansion/argent/tree/main/assets"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_argent,node_node_argent_cli,node_node_installer toneBlue
class node_node_mcp,node_node_tools_client toneAmber
class node_node_tool_server,node_node_device_tools,node_node_describe,node_node_debugger,node_node_profiler,node_node_simulator,node_node_network toneMint
class node_node_registry,node_node_skills toneRose
class node_node_native_ios,node_node_assets toneIndigo
```

## Components

### CLI & packaging

User-facing commands and distribution glue

- [argent](https://github.com/software-mansion/argent/tree/main/packages/argent): package · Top-level CLI distribution and packaging entrypoint · `packages/argent`
- [CLI runtime](https://github.com/software-mansion/argent/tree/main/packages/argent/src): runtime · Argument parsing, startup, and fatal error handling · `packages/argent/src`
- [Installer](https://github.com/software-mansion/argent/tree/main/packages/argent-installer): workspace setup · Writes MCP config, installs skills, and handles update/uninstall flows · `packages/argent-installer`

### Protocol bridge

MCP-facing boundary and process launcher

- [MCP server](https://github.com/software-mansion/argent/tree/main/packages/argent-mcp): protocol bridge · Exposes Argent capabilities over MCP and maps requests to tools · `packages/argent-mcp`
- [Tools client](https://github.com/software-mansion/argent/tree/main/packages/argent-tools-client): launcher 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](https://github.com/software-mansion/argent/tree/main/packages/tool-server): local engine · Main capability host for device, app, debugger, profiler, and workspace tools · `packages/tool-server`
- [Device tools](https://github.com/software-mansion/argent/tree/main/packages/tool-server/src/tools): device control · Boots devices and manages app launch, restart, reinstall, gestures, keyboard, and paste · `packages/tool-server/src/tools`
- [Describe](https://github.com/software-mansion/argent/tree/main/packages/tool-server/src/tools/describe): ui introspection · Builds structured UI trees from Android and iOS accessibility/native sources · `packages/tool-server/src/tools/describe`
- [Debugger](https://github.com/software-mansion/argent/tree/main/packages/tool-server/src/tools/debugger): metro/cdp · Connects to Metro and DevTools for component trees, evaluation, inspection, and logs · `packages/tool-server/src/tools/debugger`
- [Profiler](https://github.com/software-mansion/argent/tree/main/packages/tool-server/src/tools/profiler): diagnostics · Runs React Native and iOS profiling workflows and produces readable reports · `packages/tool-server/src/tools/profiler`
- [Simulator](https://github.com/software-mansion/argent/tree/main/packages/tool-server/src/tools/simulator): platform control · Manages simulator server lifecycle and related local runtime processes · `packages/tool-server/src/tools/simulator`
- [Network](https://github.com/software-mansion/argent/tree/main/packages/tool-server/src/tools/network): inspection · 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

- [Registry](https://github.com/software-mansion/argent/tree/main/packages/registry): schemas/events · Shared registry, event, error, and JSON-schema conversion utilities · `packages/registry`
- [Skills](https://github.com/software-mansion/argent/tree/main/packages/skills): prompt content · Markdown skills, rules, and agent guidance installed into workspaces · `packages/skills`

### Native assets

Bundled local binaries and platform-specific support

- [iOS native](https://github.com/software-mansion/argent/tree/main/packages/native-devtools-ios): native assets · Bundled iOS-native devtools and profiler support assets · `packages/native-devtools-ios`
- [Native binaries](https://github.com/software-mansion/argent/tree/main/assets): bundled assets · Private local binaries and shipped runtime assets consumed at execution time · `assets`

## Connections

- 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
