Introducing a new way to review your PRs.

Read the announcement

morluto / rea

Reverse engineer anything with agents, from app behavior down to native binaries.

View on GitHub

27 documents · Updated Nov 20, 2026

docs / client-configuration-and-setup

Client configuration and setup

REA connects supported agent clients to its MCP server through each client's own configuration boundary. It discovers usable client profiles, builds a reviewable setup plan, validates ownership and safety, applies only approved changes, and reports or removes registrations without taking control of unrelated settings.

Client discovery

REA treats each supported client as a product with its own registration format and configuration location. The supported-client catalog supplies the rules needed to find the right profile and to distinguish a local registration from a client that requires manual account setup.

Configuration locations

REA resolves client paths from the host, operating system, and selected environment. A client can use one file or several ordered layers. The effective registration is the view the client loads after those layers and its fallback rules are applied. Path rules follow the client that owns the file; for example, XDG-based paths and strict absolute-path rules are not interchangeable. src/…/SupportedClients.ts• L1977-2117 src/…/ClientConfigRoots.test.ts• L11-37

REA requires product evidence before it reads a client automatically. A client directory or configuration marker can show that a product is present. Shared registration storage alone is not enough because another product or REA can create it. An explicit client selection authorizes inspection when automatic discovery has no evidence. src/…/SupportedClients.ts• L1893-1933 src/…/ClientRegistrationStatus.ts• L662-694

Some clients do not expose a local file that REA can write. REA reports these clients as manual instead of treating a data directory as a local registration. This keeps hosted account setup separate from a local MCP connection. src/…/SupportedClients.ts• L386-399 src/…/SupportedClients.ts• L1862-1873

References: src/…/SupportedClients.ts• L1160-1179 src/…/SupportedClients.ts• L1893-1933 src/…/SupportedClients.ts• L1977-2117 src/…/ClientConfigRoots.test.ts• L11-37 src/…/ClientRegistrationStatus.ts• L662-694

Setup planning

Setup is a reviewable workflow. It reads host and client state without changing it, chooses clients and optional workflow files, builds exact actions, and applies them only after approval. rea setup --dry-run exposes the resolved plan without mutation. src/…/Setup.ts• L92-192 src/…/setupCommands.ts• L55-139

Client selection

Interactive setup presents detected clients as choices and selects existing REA-owned registrations by default. Detection alone does not authorize a new registration. Explicit client selections choose exact clients, while --all-detected includes every detected supported client. The approval result can select individual actions, so an approved workflow need not configure every offered client. src/…/Setup.ts• L246-342 src/…/SetupPlan.ts• L84-137 src/…/Setup.configuration.test.ts• L426-502

For each selected client, setup compares the effective registration with the desired REA connection. It creates a missing registration, updates a stale one, skips an aligned one, and stops before writing when a selected configuration is malformed or unsafe. The plan names the target, action, backup path, and relevant registration environment. src/…/SetupPlan.ts• L145-259 src/…/SetupPlan.ts• L262-334

Setup can also install REA's bundled workflow instructions. This is separate from MCP registration, so a client can receive one without the other. The command also supports optional analysis-provider and desktop-build setup as separately approved work. A failure in optional provider setup is reported without undoing client or workflow work that already completed. src/…/SetupTypes.ts• L224-242 src/…/Setup.ts• L383-399 src/…/Setup.configuration.test.ts• L207-330

The high-level setup flow is:

flowchart TD
    A[Read host and client state] --> B[Select clients and optional workflow]
    B --> C[Inspect selected configurations]
    C --> D[Build exact setup plan]
    D --> E{Approved?}
    E -- No --> F[Return plan or cancellation]
    E -- Yes --> G[Apply client changes]
    G --> H[Install selected workflow]
    H --> I[Run scoped readiness checks]
    I --> J[Report ready state or remediation]

References: src/…/Setup.ts• L195-259 src/…/Setup.ts• L277-359 src/…/Setup.ts• L383-399 src/…/Setup.ts• L401-555 src/…/SetupPlan.ts• L145-259 src/…/SetupPlan.ts• L336-418 src/…/Setup.configuration.test.ts• L426-502 src/…/Setup.configuration.test.ts• L660-804 src/…/setupCommands.ts• L262-350

Configuration validation

Validation protects the user's existing configuration and the identity of the REA installation. Setup parses the client format, checks the effective environment and client policy, verifies the registration launcher, and confirms that the target path is safe to edit. src/…/SetupClientConfiguration.ts• L495-685 src/…/ClientRegistration.ts• L163-216

Registration ownership

REA changes a rea entry only when its launcher proves that it belongs to the current REA installation. A foreign or unresolved launcher remains in place and is reported for manual review. This prevents setup from taking control of another REA installation or a hand-written server with the same name. src/…/ClientRegistrationIdentity.ts• L119-159 src/…/ClientRegistration.ts• L139-161 src/…/Setup.configuration.test.ts• L504-534

Ownership is separate from readiness. A registration can belong to REA while its timeout, policy, or transport settings are invalid. Doctor keeps that distinction so setup can repair the entry while reporting the setting that needs attention. A stored launcher can remain readable for ownership even when its transport is not an admitted local stdio connection. src/…/ClientRegistrationStatus.ts• L286-312 src/…/ClientRegistrationStatus.ts• L372-425 src/…/ClientRegistration.test.ts• L238-285

References: src/…/ClientRegistrationIdentity.ts• L119-159 src/…/ClientRegistration.ts• L139-161 src/…/ClientRegistrationStatus.ts• L286-312 src/…/ClientRegistration.test.ts• L238-285 src/…/Setup.configuration.test.ts• L504-534

Client safety checks

Setup fails closed when it cannot establish a safe target or valid configuration. It checks layered files, fallback registrations, disabled entries, and clients that can rewrite their files from memory. A running client with that behavior must be stopped before approval. src/…/SetupClientConfiguration.ts• L142-219 src/…/SetupClientConfiguration.ts• L519-524 src/…/SupportedClients.ts• L322-363

The plan is rejected when a selected file changes between inspection and publication. This prevents a plan based on old contents from replacing newer user changes. REA does not coordinate arbitrary writers, so users should not edit the same configuration while setup runs. src/…/SetupClientConfiguration.ts• L270-307 src/…/ClientConfigurationPublication.ts• L81-163

References: src/…/SetupClientConfiguration.ts• L142-219 src/…/SetupClientConfiguration.ts• L495-685 src/…/ClientRegistrationIdentity.ts• L119-159 src/…/ClientRegistration.ts• L139-216 src/…/SupportedClients.ts• L322-363 src/…/ClientConfigurationPublication.ts• L81-163 src/…/Setup.configuration.test.ts• L575-657

Configuration changes

REA updates the selected client's native representation of the MCP connection while preserving unrelated client settings. The registration receives the current REA launcher and supported selected environment values. Caller-owned policy and unrelated server settings remain under the client's control. src/…/SetupClientConfiguration.ts• L890-964 src/…/SetupPlan.ts• L472-492

Transaction and recovery

Each changed configuration is handled as one transaction. REA preserves the original bytes, publishes the new document, reads the result back, and restores the original when verification fails. Recovery snapshots are retained instead of silently replaced. src/…/SetupClientConfiguration.ts• L413-449 src/…/ClientConfigurationPublication.ts• L164-210 src/…/SetupRecoveryBackup.ts• L24-139

Private client profiles receive an owner-only backup. REA checks that an existing selected backup is a regular file, restricts it to private permissions, and preserves the original bytes without replacing an earlier matching snapshot. This keeps private configuration content from being exposed through a more permissive backup path. src/…/ClientRegistrationBackup.ts• L18-85

The same private-backup rule applies when setup or uninstall edits a private client profile. A backup failure prevents the related change and returns a failure that can be remediated rather than continuing without recovery data. src/…/SetupClientConfiguration.ts• L413-424 src/…/Uninstall.ts• L1175-1213

The result for each client distinguishes an unchanged registration from a configured one. It also records conflicts, unsafe paths, ownership refusals, write failures, readback failures, and rollback failures. These outcomes let the CLI report a repair step without hiding changes that already completed. src/…/SetupTypes.ts• L39-94 src/…/SetupClients.ts• L11-56

References: src/…/SetupClientConfiguration.ts• L366-449 src/…/ClientConfigurationPublication.ts• L164-210 src/…/SetupRecoveryBackup.ts• L24-139 src/…/ClientRegistrationBackup.ts• L18-96 src/…/Uninstall.ts• L1175-1213 src/…/SetupTypes.ts• L39-94 src/…/Setup.configuration.test.ts• L575-657

Registration environments

Setup carries supported, explicitly selected REA settings into the registration. It does not copy the full shell environment. Existing values remain unless setup supplies the same supported key, and provider values replace only matching keys. src/…/SetupTypes.ts• L24-25 src/…/SetupClientConfiguration.ts• L923-963 src/…/SetupPlan.ts• L472-491

Registration updates keep each client's native field names and preserve unrelated data. Where a client has legacy and canonical environment fields, REA accepts only an unambiguous valid form and writes one canonical form. It rejects conflicting aliases instead of choosing silently. src/…/ClientRegistration.test.ts• L41-66 src/…/ClientRegistration.test.ts• L96-180

The launcher is bound to the REA executable that runs setup. Setup uses a same-file runtime or command alias only when it can prove that the alias resolves to that executable. This lets registrations survive supported runtime-manager changes without accepting an unrelated executable as REA. src/…/ClientRegistrationIdentity.ts• L63-87 src/…/ClientRegistrationIdentity.ts• L162-214 src/…/Setup.configuration.test.ts• L536-572

The CLI controls the scope of these changes through explicit client selection, detected-client selection, tool-family and catalog-profile settings, workflow installation, and desktop-build options. The selected family and catalog profile appear in the plan before approval and are then written as registration settings. src/…/setupCommands.ts• L60-127 src/…/setupCommands.ts• L262-391 src/…/Setup.configuration.test.ts• L807-903

References: src/…/SetupClientConfiguration.ts• L890-964 src/…/SetupClientConfiguration.ts• L233-255 src/…/SetupRecoveryBackup.ts• L24-139 src/…/ClientRegistrationIdentity.ts• L63-87 src/…/ClientRegistrationIdentity.ts• L162-214 src/…/ClientRegistration.test.ts• L41-236 src/…/Setup.configuration.test.ts• L807-903 src/…/setupCommands.ts• L262-391

Registration status

Doctor reads the same client boundaries used by setup and projects each registration into a small status model. The model separates launcher identity, client activation, configuration alignment, package drift, and advisory timeout information. src/…/ClientRegistrationStatus.ts• L58-100 src/…/ClientRegistrationStatus.ts• L128-151

Status categories

The main states describe what REA can establish about the registration:

StateMeaning
alignedThe owned registration matches the supported client shape and is active.
staleREA owns the entry, but setup-managed values need refresh.
unknownREA cannot prove the launcher or native transport state.
missingNo usable REA registration is present.
invalidThe configuration or client policy cannot be safely used.
manualThe client needs a user-managed account or remote registration.

Doctor can report an advisory even when a registration is aligned. For example, a client deadline can be shorter than the known provider allowance. The advisory does not change ownership or silently change a caller-selected deadline. src/…/ClientRegistrationStatus.ts• L385-447 src/…/ClientRegistrationStatus.ts• L604-641

References: src/…/ClientRegistrationStatus.ts• L58-100 src/…/ClientRegistrationStatus.ts• L128-151 src/…/ClientRegistrationStatus.ts• L385-447 src/…/ClientRegistrationStatus.ts• L604-641

Registration removal

rea uninstall removes only registrations and managed workflow files that REA can prove it owns. It inspects all applicable client boundaries first. If a configuration is unsafe or removal could activate a foreign or shadowed entry, it keeps the file and reports the reason instead of guessing. src/…/Uninstall.ts• L187-220 src/…/Uninstall.ts• L351-389

Removal keeps unrelated servers and settings. Shared files are edited once through their owning configuration view, then the result is reported for clients that read the same file. An unresolved shared product is retained without blocking unrelated removals, while an established owned registration remains actionable. src/…/Uninstall.ts• L322-348 src/…/Uninstall.ts• L504-587

The uninstall sequence performs preflight before mutation. A removal failure stops later removals and reports completed work. Optional purge removes only REA-owned cache and state namespaces. It does not remove analysis providers such as Hopper. src/…/Uninstall.ts• L193-318 src/…/Uninstall.ts• L1199-1296

For client-specific registration workflows and native formats, see MCP client registration. For command syntax, output, and exit behavior, see command-line interface.

References: src/…/Uninstall.ts• L187-220 src/…/Uninstall.ts• L322-389 src/…/Uninstall.ts• L504-587 src/…/Uninstall.ts• L1032-1177 src/…/ClientRegistrationBackup.ts• L65-96

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the supported-client catalog, path evidence, and registration status reader aligned. A new path or profile can otherwise be writable by setup but invisible to doctor or uninstall.
  • Keep launcher ownership rules aligned between setup admission, doctor status, and uninstall removal. A change in one can turn a safe refresh into a foreign overwrite or leave an owned row behind.
  • When a client adds a configuration layer or fallback, update effective-configuration reads and removal preflight together. The active entry can change when an earlier layer or fallback becomes visible.
  • Preserve the setup plan's client environment contract when adding a supported REA setting. The setting must be validated, written in the client's native shape, and visible to the client after restart.
  • Keep native alias normalization aligned with each client's parser and writer. Accepting two equivalent fields can still create duplicate or conflicting data in the client's document.
  • Keep private-profile backup permissions aligned across setup and uninstall. A new backup or recovery path must remain an owner-only regular file and must preserve the bytes that the planned edit inspected.
  • Keep optional provider work separate from approved client actions. A provider failure must remain visible without silently removing successful registrations.

Important failure modes

TriggerConsequenceGuard
Existing rea entry points to a foreign or unresolved REA launcherSetup does not overwrite itLauncher ownership admission requires a proven current entrypoint
Selected configuration is malformed or has invalid REA settingsThe selected setup plan stops before mutationPreflight parses each selected client and reports remediation
Registration uses a non-stdio transport or malformed stored argumentsOwnership facts may be retained, but the connection is not ready for local setupSeparate launcher parsing from stdio connection admission
Client file changes after planningThe client is not updated from stale contentsPublication checks the selected file before and after the write
Running client can rewrite its configuration from memoryThe new registration can disappearSetup requires the client to be fully quit when the client has this behavior
Native environment aliases conflict or contain invalid valuesREA refuses the update instead of choosing a valueParse aliases as one client policy and emit one canonical field
Private backup path is not a regular owner-only fileSetup or uninstall does not proceed with an unprotected recovery copyBackup handling checks the path and applies private permissions before preservation
Optional provider download fails during approved setupSetup reports remediation while completed client work remains appliedKeep provider actions separate from client and workflow actions
Shared storage has no product applicability evidenceUninstall retains the shared fileRemoval separates product evidence from REA ownership evidence
Removing REA would expose a foreign duplicate or fallbackRemoval stops to avoid activating another registrationUninstall checks shadowed entries and fallback views before editing

Key files

FileWhy to read it
src/…/SupportedClients.tsDefines the supported client catalog, path resolution, discovery evidence, and manual boundaries.
src/…/ClientConfigRoots.tsDefines the host and environment rules used to resolve client configuration roots.
src/…/Setup.tsShows the end-to-end discovery, approval, apply, and final-readiness flow.
src/…/SetupPlan.tsExplains client selection, preflight, and the actions shown for approval.
src/…/SetupClientConfiguration.tsShows how one client registration is validated, updated, verified, or rejected.
src/…/ClientRegistration.tsDefines launcher parsing, native policy checks, and safe field normalization.
src/…/ClientRegistrationBackup.tsDefines private-profile backup protection shared by setup and uninstall.
src/…/ClientRegistrationStatus.tsDefines doctor’s registration states and remediation model.
src/…/ClientConfigurationPublication.tsDefines safe publication and readback of changed configuration.
src/…/SetupRecoveryBackup.tsDefines matching recovery snapshots and their verification.
src/…/Uninstall.tsExplains ownership-safe removal and reporting across shared or layered files.
src/…/setupCommands.tsDefines the user-facing setup, doctor, uninstall, and setup-scope options.