macOS Desktop — Your aachat Guide on Mac

aachat Desktop puts a guide in front of your Mac windows. Talk to it to set up aachat or get help using aachat. The guide prepares tools and settings, and walks you through actions that need you, such as creating an account or signing in through a browser. Project, Session, and document screens remain in WebUI.

This page describes Desktop 1.0 and later. You can choose Claude Code or Codex as the runtime for the guide. Download the app from the official Desktop release. Older Desktop 0.x does not include the guide described below. For terminal, Linux, WSL2, or headless use, see CLI setup.

Install and requirements

The app targets Apple Silicon on macOS 14 or later. Download the DMG from the official release Assets, copy aachat to Applications, and launch it. The .app.tar.gz and .sig files are for app updates.

You need a Claude or ChatGPT account with access to your chosen runtime, and an internet connection for initial preparation. The app prepares Node.js and your chosen runtime in its own folder; you do not need to install them first. The guide helps you prepare your GitHub account, Git authentication, and other requirements for doing work in aachat.

First run

Automatic preparation, the four menus, and the confirmation flow below describe the new experience in development. Implementation and PR completion are separate from release availability and acceptance on a real Mac.

1. Open aachat and choose Claude Code or Codex. A saved choice starts preparation directly.
2. The app prepares the conversation software and guide information.
3. When asked, select ブラウザを開く (open browser), complete sign-in for your chosen service, and return. For Codex, enter the displayed code in the browser. The conversation starts after the app confirms authentication.
4. The guide says it will prepare aachat, then checks and performs the necessary installation, authentication, startup, and repairs. Follow instructions for actions that need you and tell the guide when you are done.
5. Once it verifies aachat is usable, it shows 実現したいことを相談する (discuss what you want to achieve), プロジェクトの進み具合を見る (view project progress), 困っていることを解決する (resolve a problem), and Macの作業環境を整える (prepare the Mac environment). Free text is also available.

You can reply during preparation once the guide is running. Work requests are discussed after preparation finishes. Startup handles only what is needed to use aachat; broader Mac environment changes require agreement to a concrete plan.

If preparation or sign-in fails, read the reason in the bubble and select もう一度 (try again). Opening a browser alone does not count as a completed sign-in.

Talking to the guide

The guide clarifies what you want to achieve through questions, writing, and vertical diagrams. It summarizes the result, completion criteria, scope, and assignee. Select この内容で始める (start with this plan) on the latest summary to hand that content to an aachat Agent. Casual agreement or a typed reply alone does not start the work. Corrections require a new summary and confirmation. The progress menu reads the selected Team and Project to report delivered results, ongoing work, and decisions waiting for you. Returning to the menu does not start work.

The small transparent window stays in front of other windows. Drag the character to move it. Press Enter to send a reply, or Shift+Enter for a new line. Confirming Japanese text composition does not send the reply. You can send while the guide is responding; replies are processed in order. A short message such as “確認しています…” (checking) indicates work in progress.

Scroll upward in the bubble to read earlier messages from this app run. Click × (ガイドを閉じる) at the top right of the bubble to hide the guide, including its character. Your conversation, unsent draft, and runtime selection are kept, and work in progress continues. Replies do not show the window automatically; click the Dock icon to return to the same conversation. Quitting ends that conversation. The next launch checks the current state and prepares aachat using your saved runtime. Unsubmitted discussions and start confirmations are not saved. Work already handed off can be checked in its Project records.

To start over, choose ガイドをやり直す (reset guide) from the app menu. This clears the runtime selection, conversation, and unsent confirmations, returning to the initial screen. The shared aachat root, work files, and Claude or Codex sign-in credentials are kept. It does not uninstall aachat or other tools the guide has installed.

Prepare the Mac environment together

Choose Macの作業環境を整える (prepare the Mac environment), or ask the guide to prepare the environment. It checks existing tools and proposes the missing software, required dependencies, setting changes, download sizes, and actions that need you. Changes begin after you agree to that concrete plan. You can exclude items in your reply. Approved, independent work continues while a login is waiting or another item has failed.

The offer covers aachat and the selected runtime; Git, GitHub CLI, ripgrep, and jq; PATH and noninteractive command settings; existing instructions, skills, and MCP connections; standard credential storage; background execution and notifications; sleep settings while connected to power; Homebrew when needed; uv; browser operation; Google Drive, Gmail, and Google Calendar; Notion; ImageMagick; and FFmpeg. uv and image/audio/video conversion tools are included without requiring you to specify a creative project first.

For browser operation, Codex uses the ChatGPT app, Computer Use, and a browser extension; Claude Code uses Claude in Chrome. For each Google service, the guide confirms whether you use it, your account, and the access scope. It also confirms your Notion account, workspace, and access scope, then uses official connections. The guide walks you through sign-in and OS permissions. Connection checks do not send mail, invite people, edit pages, or incur charges.

Poppler, LibreOffice, and DuckDB are not installed or updated; existing copies are not removed. An item requiring one of them as a new dependency is deferred. The offer does not add document conversion suites, OCR, transcription models, generation APIs, or development tool suites, or upgrade all installed software.

Results distinguish usable items, prepared items awaiting verification, and skipped or failed items. Working inside the guide does not prove that an aachat Agent can use a tool or connection; any checks still needed in a new aachat Session are stated explicitly. Ordinary settings are backed up before changes, without credentials. Ask to undo changes and the guide checks later edits before restoring its own changes. Uninstalling software or revoking permissions requires a separate confirmation. Relaunching the app does not reuse earlier consent to repeat setup automatically.

Prepare environment variable storage

After authentication and connection of the selected Mac, the guide checks Keychain as part of the environment plan you approved, without asking for a test secret. It creates a disposable item, reads it in another process, deletes it, and verifies that the Mac, root, and owner match the WebUI before reporting success. New Macs create settings on the first save and do not need adoption first. Only legacy settings need human-terminal adoption; changing an existing default uses aachat env default --destination local-keychain with human confirmation.

Afterward, enter a name and value in Tools > Secrets on the connected Mac and select Save. Normal Keychain saving, read verification, and Agent Allow run noninteractively. Only Agents requesting that name are eligible for access, beginning in a new Session that loads the environment. Do not paste secret values into the conversation.

“Saved, but access could not be verified.” means the value is saved but readability is unconfirmed. Do not create or send it again. Tell the guide the Mac and variable name. First check aachat env keychain-access --name NAME on the same Mac/root. For permission_denied, check the signature and login Keychain state; use --reauthorize in a human terminal only when needed, and verify the subsequent noninteractive read. Refresh the WebUI and use Allow if permission still needs repair, without overwriting the value. Saved · Allowed in the list reports name presence and Agent permission, not proven readability.

The guide does not change your normal Keychain, ACL, lock, or sleep settings without agreement. Disabling automatic locking affects the entire login Keychain and is a choice you make after the guide explains that impact. A successful check describes the current state; it does not promise that future updates or logins will never need authorization.

Starting aachat and updating the app

Desktop itself has no aachat start/stop controls, runtime status panel, or Open aachat button. In the new experience, the guide checks aachat on each launch and performs necessary installation and startup. It does not start a duplicate runtime or automatically open WebUI when preparation finishes. CLI commands such as aachat up and aachat launcher remain available. Quitting Desktop does not stop an aachat runtime the guide started through the CLI.

The app retains its own update feature. Follow the update prompt to apply an update and relaunch. App updates and CLI updates are separate. To update the CLI manually, use aachat update (see Setup).

When a Session says “Live view is unavailable with this version.”

This WebUI message means the CLI running that Session is too old. The runtime owner should check aachat --version on the machine running it and use aachat update. After checking that no work is running, restart the runtime and select Retry in the Session screen.

For a terminal running aachat up, press Ctrl+C and run it again. For a runtime started by an older Desktop app or the CLI launcher, use aachat launcher stop and aachat launcher start. Automatic preparation does not replace the update and restart procedure for a running runtime.

Live updates could not keep up. and Could not update the live view. do not indicate a version problem. Select Retry to reload the view. For other issues, see Troubleshooting.