# How the Onboarding System in Desktop Commander MCP Works: Complete Technical Guide

> Explore Desktop Commander MCP's onboarding system technical guide. Learn how dual flags manage new and experienced user flows for a tailored welcome experience.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: technical-guide
- Published: 2026-07-29

---

**Desktop Commander MCP uses a dual-flag eligibility system to distinguish new from experienced users, injecting welcome messages only during the first launch through A/B-tested flows controlled by `welcomeOnboardingEligible` and `pendingWelcomeOnboarding` flags in the config store.**

The Desktop Commander MCP repository implements a sophisticated onboarding system that determines exactly when to display welcome guidance to new users while maintaining a frictionless experience for veterans. This technical deep dive examines how the codebase differentiates between fresh installations and returning users through persistent state flags, feature flags, and strategic injection points in the server lifecycle.

## New vs. Experienced User Detection

The onboarding system relies on two distinct boolean flags stored in the configuration manager to classify users.

### Eligibility Flags and First-Run Detection

When the configuration file is created for the first time, the system automatically sets `welcomeOnboardingEligible` to `true`. This flag acts as a permanent marker indicating a brand-new installation. Simultaneously, the `pendingWelcomeOnboarding` flag is set to `true`, creating a pending state that survives process restarts until a decision is made.

In [`src/utils/welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/welcome-onboarding.ts), the eligibility check occurs at lines 41-45, where the code verifies `welcomeOnboardingEligible` is present. The pending status is validated at lines 48-53, ensuring the onboarding request remains active across server restarts until the user either sees the welcome page or is assigned to the control group.

**Experienced users** are identified by the absence of the eligibility flag (indicating an older configuration) or by having the pending flag cleared. Once `pendingWelcomeOnboarding` is set to `false`, the user will never trigger the onboarding flow again, regardless of subsequent restarts.

## The Onboarding Execution Flow

The onboarding message injection happens during the server initialization sequence, seamlessly integrating with the LLM response stream.

### Server Startup Injection Point

In [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) around line 1565, the server queries the usage tracker to determine if onboarding should trigger:

```typescript
const onboardingResult = await usageTracker.getOnboardingMessage();

```

If the result indicates onboarding is required, the system injects the welcome message into the LLM response content at lines 1586-1592. This injection point ensures the user receives contextual guidance within their first interaction without requiring a separate modal or popup window.

### Welcome Page Handler Logic

The core onboarding logic resides in [`src/utils/welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/welcome-onboarding.ts). When the server detects a pending onboarding state, it delegates to this utility to determine whether to display the welcome page or skip it based on A/B test assignments and client exclusions.

## A/B Testing and Variant Assignment

Desktop Commander MCP implements controlled experiments to measure onboarding effectiveness through the `showOnboardingPage` feature flag.

### Treatment vs. Control Groups

The variant assignment occurs through `hasFeature('showOnboardingPage')` evaluated at lines 80-82 in [`welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/welcome-onboarding.ts).

**Treatment:** Users in the treatment group trigger `openWelcomePage()` (lines 103-107), which displays the welcome interface and immediately updates the persistence layer by setting `sawOnboardingPage` to `true` and clearing `pendingWelcomeOnboarding`.

**Control:** Users assigned to the control group bypass the welcome page. The system clears the `pendingWelcomeOnboarding` flag and records the decision via the `capture()` helper at lines 84-88 and 89-95, ensuring accurate analytics tracking for conversion rate analysis.

Both branches utilize the `capture()` analytics helper to emit telemetry events, enabling the team to measure engagement differences between users who see the onboarding versus those who proceed directly to functionality.

## Configuration and Exclusions

The system provides multiple mechanisms to bypass onboarding for specific deployment scenarios or client types.

### Client-Specific Exclusions

Certain client implementations (such as custom UI wrappers) can be excluded from the onboarding flow via the `welcome_page_excluded_clients` feature flag. The helper function `isWelcomePageClientExcluded()` at lines 19-29 in [`welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/welcome-onboarding.ts) checks the client name against this exclusion list.

If a client matches the exclusion criteria, the system immediately calls `skipWelcomePageOnboarding()` to clear the pending flag without displaying any welcome content, preventing redundant guidance in embedded or white-label implementations.

### Command-Line Overrides

Users can suppress the entire onboarding system by launching the CLI with the `--no-onboarding` flag. In [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) at lines 44-50, the argument parser detects this flag and sets the `DISABLE_ONBOARDING` environment variable, which short-circuits all subsequent onboarding checks regardless of persistence state.

```bash

# Launch Desktop Commander MCP without onboarding

desktop-commander --no-onboarding

```

## State Persistence Model

All onboarding-related state lives in a JSON-based configuration store accessed through the config manager.

### Config Store Schema

The following keys control the onboarding lifecycle:

| Key | Purpose |
|-----|---------|
| `welcomeOnboardingEligible` | Permanent marker set only when the config file is first created |
| `pendingWelcomeOnboarding` | Transient state indicating an onboarding decision is pending |
| `sawOnboardingPage` | Confirmation that the welcome page was displayed |
| `onboardingState` | Granular tracking used by `usageTracker` for attempt counts and timestamps |

These values are accessed throughout the codebase via `configManager.getValue()` and `configManager.setValue()`. The `usageTracker` module (in [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts)) maintains additional metadata including attempt counters, last-shown timestamps, and prompt utilization metrics to support sophisticated nudging strategies beyond the initial welcome flow.

### Code Example: Client Exclusion Check

```typescript
// src/utils/welcome-onboarding.ts
if (isWelcomePageClientExcluded(clientName)) {
  await skipWelcomePageOnboarding();   // clears pending flag
  return;
}

```

## Summary

- **Dual-flag detection** distinguishes new installations (`welcomeOnboardingEligible`) from decisions-in-progress (`pendingWelcomeOnboarding`), ensuring returning users never see repeated onboarding.
- **A/B testing** via the `showOnboardingPage` feature flag allows the team to measure conversion rates between treatment and control groups.
- **Strategic injection** occurs in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) through `usageTracker.getOnboardingMessage()`, embedding guidance directly into the LLM response stream.
- **Flexible exclusions** support both client-specific blocklists and CLI overrides via `--no-onboarding`.
- **Persistent state** stored in the JSON config manager ensures onboarding decisions survive process restarts and respect user history.

## Frequently Asked Questions

### How does Desktop Commander MCP determine if I am a new or experienced user?

The system checks for the presence of `welcomeOnboardingEligible` in your configuration file. This flag is only written when the config file is created for the first time. If you lack this flag entirely (indicating an older installation) or if your `pendingWelcomeOnboarding` flag has been cleared to `false`, the system classifies you as an experienced user and skips the welcome flow automatically.

### Can I disable the onboarding system without modifying configuration files?

Yes. Launch the application with the `--no-onboarding` command-line argument. This sets the `DISABLE_ONBOARDING` environment variable early in the startup sequence (handled in [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) lines 44-50), which bypasses all eligibility checks and prevents any onboarding messages from being injected into your session.

### What happens if my MCP client is on the exclusion list?

If your client name matches the `welcome_page_excluded_clients` feature flag list, the function `isWelcomePageClientExcluded()` returns `true` at lines 19-29 in [`welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/welcome-onboarding.ts). The system then calls `skipWelcomePageOnboarding()` to clear the pending flag immediately, allowing you to proceed with normal operation without seeing the welcome page.

### Where is the onboarding state stored, and can I reset it manually?

All state persists in the JSON configuration store managed by `configManager`. Key values include `welcomeOnboardingEligible`, `pendingWelcomeOnboarding`, and `sawOnboardingPage`. You can manually reset your onboarding status by clearing these keys from the configuration file, though modifying `welcomeOnboardingEligible` specifically will re-qualify you as a "new" user on the next restart.