---
title: "launch"
description: "macOS alternative entry for the normal Codex window."
image: "https://daftai2026.github.io/incodex/social.svg"
---

> Documentation Index
> Fetch the complete documentation index at: https://daftai2026.github.io/incodex/llms.txt
> Use this file to discover all available pages before exploring further.

# launch

{/*
[INPUT]: 依赖launch解析、安装记录与macOS启动分支。
[OUTPUT]: 说明共享 Finder 入口、旧入口迁移与移除边界。
[POS]: 普通宿主命令页；会话归open，包集成归install。
[PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
*/}

> On macOS, this alternative shares the existing private-window implementation but does not provide full parity with `install`.

`inc` and `incodex` are interchangeable for this command and its flags.

```bash
incodex launch [--dry-run] [--app <path>]
incodex launch --remove [--dry-run] [--yes]
```

`launch` starts normal Codex on macOS without copying, patching, or re-signing the app. It selects the existing integration automatically:

- **Already installed with Incodex:** reuse the recorded install, its Loader, IPC, Runtime, menus, and permission flow. A normal LaunchServices request opens or activates that app. No additional CDP controller starts and no Runtime is published. You do not need to uninstall first.
- **Uninstalled official app:** start the unmodified app with loopback CDP. Reuse the shared hat control and action factory, forwarding private-window requests to the existing Rust `open` lifecycle.

Windows keeps the existing `install` integration and official icon. This macOS alternative does not add a Windows launcher bundle or a second injection path.

If the standard Codex profile already belongs to a verified live Incodex launcher, `launch` activates that existing window even when its app bundle is at another path. The Finder entry keeps the requested target for later starts. A profile lock alone is not permission to control a process. Otherwise, the installed branch uses normal activation; the CDP branch reuses its own captured window, and an app started by another route must first exit normally. The command does not close Codex.

Before starting Codex, `launch` publishes `/Applications/ChatGPT - Inc.app`. It migrates exact Incodex-owned entries from `~/Applications/ChatGPT - Inc.app` and `~/Applications/Incodex Launcher.app` after it publishes and verifies the shared entry. Unknown, modified, or other-user entries remain untouched. It does not create `/Applications`, fall back to a user entry, or request `sudo`. A conflicting external bundle is rejected before the official app starts. This thin shell invokes the same CLI and preserves `HOME`. It does not copy configuration or sessions. Installed CLI links remain channel-stable rather than pinning a Homebrew Cellar version. The Finder entry exits; only the CDP branch retains an App-scoped CLI, so keep that terminal command running. An accepted launch request is not proof of visible UI readiness. The Finder entry has no separate error UI. Use the terminal command for immediate errors, or read `~/.incodex/launchers/launch.log` for its recent target, stage, and bounded error receipts. The private log keeps at most eight events within 4 KiB; dry-run and entry removal do not write it. A recorded `installed-requested` stage is only a LaunchServices request, not a window-ready result. The launcher follows the selected ChatGPT or Codex Dock icon style and falls back to the host's file icon if that resource is unavailable. It does not watch for Dock changes in the background. Run `inc update`, then `incodex launch` to refresh it. This does not require re-signing, reinstalling, or restarting the host. The [launcher guide](/incodex/en/launchers/) shows the Finder location and migration steps.

## Create and use the Finder entry

1. Run `incodex launch --dry-run` to preview the target.
2. Run `incodex launch`, or select **Launch** in the macOS `inc` menu. **Open** opens a private window directly instead.
3. In Finder, choose **Go › Go to Folder**, enter `/Applications`, and press Return. Open **ChatGPT - Inc.app** there. Click the in-app hat-glasses control to open a private window.

The Finder entry reuses the same `launch` command, not another Runtime or installer. It remembers the app selected when the entry was created. Running `launch --app <path>` replaces that remembered target.

## Remove only the Finder entry

```bash
incodex launch --remove --dry-run
incodex launch --remove
```

The command prints a plan and asks once in a terminal. Non-interactive removal requires `--yes`. It removes only recognized Incodex launcher bundles, including the old name, without starting or closing Codex, uninstalling app integration, or deleting Runtime and sessions. It still works when the original Codex app is missing. Do not combine `--remove` with `--app`.

`incodex uninstall` removes app integration; it is not the Finder-entry removal command. Script-managed macOS CLI self-uninstall also removes a recognized owned Finder entry so it cannot point at a deleted CLI.

## Flags

| Flag | Meaning |
| --- | --- |
| `--dry-run` | Preview launch or entry removal without opening a window or writing files. |
| `--remove` | Remove only the recognized Incodex Finder entry. |
| `--yes` | Confirm entry removal without a terminal; valid only with `--remove`. |
| `--app <path>` | Select an official Codex `.app`; the default is `/Applications/ChatGPT.app`. |

## Runtime updates

An installed app keeps its existing Runtime update path. The contracts below apply only to the uninstalled CDP branch.

While `launch` is running, compatible updates to the injector and shared action factory use the existing `UiUpdate` transaction. The renderer and action controller must both acknowledge the new generation. A missing or superseded acknowledgement rolls the change back. A native-open request verifies that its CLI contains the selected Runtime; a stale CLI fails without publishing older assets. Changes to native or other non-hot-swappable Runtime assets require a restart; this path does not provide full feature parity with `install`.

The uninstalled CDP branch does not supply existing Dock/status menus or installed permission probes. `incodex install` remains the existing app-integration path. Its private windows use the WindowServer close observer and do not require CLI or launcher Accessibility access. This does not grant or transfer the official app’s permissions.

While its private child is alive, repeated hat clicks reuse that owner and request foreground activation. Success requires the private guardian’s actual page and system-activation acknowledgement, not merely a successful pipe write. A missing control capability or failed activation fails only that request and retains the private window. If no normal page remains, reactivation fails rather than silently launching another app.

## Examples

```bash
incodex launch --dry-run
incodex launch
incodex launch --app "/Applications/ChatGPT.app"
```

Use `incodex launch --help` for your installed version. Run `inc update` to update to the latest stable release.

Source: https://daftai2026.github.io/incodex/en/commands/launch/index.mdx