--- title: "macOS Desktop — Start aachat from an App" description: "Install the Mac app, sign in, start the local runtime, and distinguish app updates from CLI updates." --- # macOS Desktop — Start aachat from an App aachat Desktop checks your Mac, helps install the local CLI, starts the runtime, and opens aachat in your browser. The Project, Session, and document screens are in the WebUI. Use Desktop when you want an app to guide local startup; use the [CLI setup](/en/docs/setup) for terminal, Linux, WSL2, or headless operation. ## Install and prepare The [official Desktop release page](https://github.com/kensaku63/aachat-desktop-releases/releases/latest) provides the Mac download. The published distribution targets **Apple Silicon and macOS 14 or later**. Choose the DMG from its assets, open it, and copy aachat to **Applications** before launching it. The updater archive is for app updates; it is not the normal first-install path. Check the release page's requirements when downloading a newer version. You need a GitHub account, Git, Node.js **22 or later** with npm, and a locally installed and authenticated coding runtime (Claude Code or Codex). Desktop's GitHub sign-in does not sign you into that coding runtime. If a task will use a private repository, the local Git credentials also need access to that repository. 1. Open aachat from Applications. If the CLI is missing, choose **Install aachat** first, then follow the instructions returned by the CLI. 2. Choose **Sign in with GitHub** and complete browser authorization. Allow the browser to return to aachat. If it fails, use **Try sign-in again** and complete the new attempt. 3. Use **Install aachat** when offered to install the managed CLI. If Git is missing, use **Install Git** and finish the macOS tools installation. **Download Node.js** opens the download page; complete that installation yourself. 4. After installing an external prerequisite, return to the app. The CLI checks completion and continues startup. Opening a download page alone does not install the prerequisite. 5. Once setup is complete, aachat starts and opens in your browser automatically. On subsequent visits, open the app to start using aachat. **Open aachat** is also available. 6. Obtain an Agent and follow [Setup](/en/docs/setup) to create a Project with a Lead and Brief. Check the first Session's response. Desktop readiness verifies the local runtime, not that every Agent can execute its first task. ## Closing the window and runtime ownership Closing the window hides it. Quitting or updating Desktop, or closing the browser, does not stop the runtime. Desktop asks the CLI to start a one-shot macOS `launchd` job. The runtime continues after the app quits or updates. It does not start at login or automatically retry abnormal exits. Follow the displayed instructions to retry a failed startup. If a runtime already runs from a terminal, it is left running. Plain `aachat up` can replace an existing daemon; inspect with `aachat status` or `aachat launcher status` instead. Use `aachat launcher stop` to stop and unregister the runtime job started by the app. For a terminal-owned runtime, use that terminal's `Ctrl+C`. Stopping interrupts local work and synchronization. The CLI owns authentication, prerequisites, status and recovery. Desktop displays its result. After a forced exit, the CLI checks the exclusive runtime lock and process start identity before recovering a leftover status file. Manual status-file deletion is unnecessary. ## App updates and CLI updates Update controls vary by app version. The update and recovery guidance below applies to versions that show a separate **Update and relaunch** button in the update section. If your app shows different controls, check the displayed actions and the [official Desktop release page](https://github.com/kensaku63/aachat-desktop-releases/releases/latest). Desktop checks for its own updates in the background when the process starts or its window is reopened. **Update ready** with a target version means the app update is prepared. Choose the displayed **Update and relaunch** to apply it and restart the app. When the update section shows a separate **Update and relaunch** button, you can choose it without first completing the primary sign-in, installation, or runtime recovery action. It can appear while the runtime has a problem or is preparing, as long as an update is ready. Wait for any other action in progress to finish. The original diagnosis and recovery action remain; updating the app does not guarantee that the runtime problem is resolved. **Later** is available whenever an update is offered, including during setup. App update display, dismissal and failure never replace CLI state, startup, open or recovery actions. This updates the Desktop app. `aachat update` updates the CLI, and `aachat up` checks for CLI updates at startup. These have separate versions and release artifacts. Installing a Desktop update is not proof that the CLI or a running coding-agent Session has changed version. ## When startup or update stops | What you see | What to do | |---|---| | Missing Git, Node.js, or npm | Complete the external installation, then return to the app for the CLI to check it. Node.js must report version 22 or later | | GitHub sign-in does not finish | Use **Try sign-in again**; finish the fresh browser flow and return to the app | | **Action needed** after startup | Read the reason. Use **Try again** only after resolving the displayed prerequisite or runtime problem | | Runtime status is invalid or the process cannot be inspected | Use **Open aachat support** with the displayed reason. The CLI recovers leftover records of exited processes | | `aachat` and `chat` versions do not match | Follow the CLI installation action to restore a consistent managed CLI set, then check again | | Background update check failed | A check failure alone does not change the runtime state, reason, or primary action. Follow the displayed startup, open, or recovery action. No update offer does not mean an update failed to install or the runtime stopped | | App update failed to install | Use **Open update support** in the app-update section. CLI startup, open and recovery actions remain available | | The app reports that relaunch after an update did not complete | Use **Open Applications** in the app-update section. CLI state and actions remain available | | App says ready but an Agent cannot work | Check that Agent's runtime authentication, ownership, and Launch Report using [Troubleshooting](/en/docs/troubleshooting) | An app installation or relaunch failure alone does not mean that a running runtime has stopped or failed. To report a problem, record the update stage that stopped, the original recovery action, the app's reason and version, `aachat --version`, and the relevant redacted output of `aachat status`. Do not include JWT files, API keys, or environment secret values. See [Environment](/en/docs/environment) for granting task-specific secrets after installation.