# How to Customize or Disable the Onboarding Flow in Desktop Commander MCP

> Customize or disable Desktop Commander MCP onboarding with the --no-onboarding flag or by modifying configuration files. Control the user experience easily.

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

---

**Pass the `--no-onboarding` flag when launching the MCP server to completely suppress all onboarding prompts, or modify configuration files and source components to customize the experience.**

Desktop Commander MCP displays an onboarding experience to new users during their first session. You can disable this flow entirely using command-line flags or tailor it by editing specific source files in the `wonderwhy-er/DesktopCommanderMCP` repository. This guide explains the exact mechanisms that control onboarding behavior.

## How the `--no-onboarding` Flag Works

The entry point in [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) parses command-line arguments and sets a global variable that downstream components check before displaying onboarding elements.

At lines 44-51, the server detects the flag:

```typescript
const DISABLE_ONBOARDING = process.argv.includes('--no-onboarding');
if (DISABLE_ONBOARDING) { logToStderr('info', 'Onboarding disabled via --no-onboarding flag'); }
(global as any).disableOnboarding = DISABLE_ONBOARDING;

```

This global flag propagates to two critical files. In [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts) (lines 45-48), the system checks the flag and returns early:

```typescript
if ((global as any).disableOnboarding) {
  return false; // skip onboarding
}

```

Similarly, [`src/utils/welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/welcome-onboarding.ts) (lines 45-52) reads this global setting to prevent the browser tab from opening.

## Running Desktop Commander MCP Without Onboarding

To launch the server and bypass all onboarding prompts, append the flag to your start command:

```bash

# Suppress onboarding completely

desktop-commander-mcp --no-onboarding

```

When present, this flag overrides both feature-flag settings and local configuration, ensuring no welcome pages or injection prompts appear.

## Customizing the Onboarding Experience

To modify rather than disable the flow, edit these specific components:

### Feature Flag and Configuration Controls

The `shouldShowOnboarding()` function in [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts) checks multiple gatekeepers:

- **Remote feature flags**: `featureFlagManager.get('onboarding_injection')` enables or disables onboarding globally.
- **Local configuration**: `configManager.getValue('onboarding_injection')` reads user-specific settings from [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json).

### Retry Logic and Attempt Limits

Lines 78-89 of [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts) contain the `shouldShowOnboarding()` logic that controls how many times the prompt appears and the delay between attempts. Edit these lines to change the frequency of onboarding injections.

### Welcome Page Content and A/B Testing

The [`src/utils/welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/welcome-onboarding.ts) file uses `hasFeature('showOnboardingPage')` to determine whether to open the browser. To force the welcome page for all users, modify the A/B test assignment:

```typescript
// Force treatment for every new install
const shouldShow = true;   // ← replace the call to hasFeature(...)

```

The actual HTML content rendered in the browser is controlled by [`src/utils/open-browser.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/open-browser.ts).

## Disabling Onboarding via Configuration File

As an alternative to the command-line flag, add this entry to your [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json):

```json
{
  "onboarding_injection": false
}

```

The configuration manager reads this value in [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts), causing `shouldShowOnboarding()` to return `false` even without the `--no-onboarding` flag.

## Summary

- **Pass `--no-onboarding`** when starting the server to completely disable the flow via the global flag set in [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts).
- **Edit [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts)** to modify retry logic, attempt limits, and feature-flag checks.
- **Modify [`src/utils/welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/welcome-onboarding.ts)** to control the welcome page A/B test and browser launch behavior.
- **Use [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json)** with `"onboarding_injection": false` for a persistent disable without command-line flags.
- **Update [`src/utils/open-browser.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/open-browser.ts)** to change the actual HTML content shown to users.

## Frequently Asked Questions

### Where is the `--no-onboarding` flag parsed in the source code?

The flag is parsed in [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) at lines 44-51 using `process.argv.includes('--no-onboarding')`. When detected, it sets `(global as any).disableOnboarding = true`, which [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts) and [`src/utils/welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/welcome-onboarding.ts) check before showing any onboarding elements.

### Can I disable onboarding without using the command-line flag?

Yes. Set `"onboarding_injection": false` in your [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json) file. The `configManager.getValue('onboarding_injection')` call in [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts) will read this setting and prevent onboarding from displaying.

### How do I change how many times the onboarding prompt appears?

Edit the `shouldShowOnboarding()` function in [`src/utils/usageTracker.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/usageTracker.ts) around lines 78-89. This function contains the logic for attempt counting and delay intervals between onboarding prompts.

### What file controls the welcome page content?

The HTML content for the welcome page is managed in [`src/utils/open-browser.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/open-browser.ts), which is called from the `openWelcomePage` function in [`src/utils/welcome-onboarding.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/utils/welcome-onboarding.ts). Edit this file to customize the visual presentation shown to new users.