# gdmux · gid · gdm — Install and start your first task

[한국어](QUICKSTART.md) · [English website](https://gdmux.pages.dev/en/start/)

The Mac tools are public preview `preview-20261008.3` for macOS 13 or later, on Apple Silicon and Intel. The downloadable executables are Developer ID signed and Apple notarized. You do not need Rust, Bun, a GitHub login, or an administrator password for the default installation.

- **gdmux** arranges terminals and AI tasks in a workspace.
- **gid** lets you code through conversations with Codex or Claude.
- **gdm** records requirements, check commands, and real execution evidence.

Each tool works independently. AI features require the corresponding official CLI, sign-in, and access to that AI service. AI subscriptions are not included.

## 1. Install on your Mac

Open your Mac terminal and run:

```sh
curl -fL https://gdmux.pages.dev/install.sh -o /tmp/gdm-tools-install.sh
zsh /tmp/gdm-tools-install.sh --tool all
```

To install one tool, replace the second line with one of these:

```sh
zsh /tmp/gdm-tools-install.sh --tool gdmux
zsh /tmp/gdm-tools-install.sh --tool gid
zsh /tmp/gdm-tools-install.sh --tool gdm
```

The default destination is `~/.local/bin`. gdmux includes `gdmux`, `gdmuxd`, `gdmuxctl`, and `gdmux-remote`. gid and gdm each install one executable. The base installation does not change your shell startup files or AI agent settings.

Open a new terminal after installing. If you see `command not found`, add this line to your shell configuration (`~/.zshrc` for the default zsh shell), then open a new terminal:

```sh
export PATH="$HOME/.local/bin:$PATH"
```

To use another installation prefix, add `--prefix /absolute/path`; executables are placed in its `bin/` directory. For new gid tasks created from an iPhone, keep gid at the default `~/.local/bin/gid` path.

### Optional: gdm skills for AI agents

Use one of these installation commands if you also want gdm skills:

```sh
zsh /tmp/gdm-tools-install.sh --tool all --with-skills
# Or install gdm and its skills only:
zsh /tmp/gdm-tools-install.sh --tool gdm --with-skills
```

Skills add workflows for Codex, Claude, and Pi, a `gdm-pi` launcher, and a Codex task gate that checks verification at the end of a task. Existing Codex hooks are preserved and backed up. The installer may add `~/.local/bin` to your shell PATH if needed. Existing gdm skills are updated. It does not copy other agents’ sign-in details. Start a new AI session after installation.

## 2. Start gdmux

Run `gdmux` inside a project folder. A modern terminal with 24-bit color support is recommended.

For a prefix shortcut, press **Ctrl+B**, release the keys, then press the next key:

| Next key | Action |
| --- | --- |
| `a` | Start a new task |
| `v` / `s` | Split the view |
| `w` | Show all tasks |
| `p` | Find an action |
| `?` | Show shortcut help |
| `m` | Open remote connection settings |

**Ctrl+Q** leaves the view. Work continues while the background session manager is running. Run `gdmux` again to reconnect. Running processes do not survive a Mac shutdown or restart.

## 3. Start gid

Install the official Codex or Claude CLI first. Then check authentication and sign in to the service you want:

```sh
gid auth status
gid login codex
# Or:
gid login claude
```

In your project directory:

```sh
gid
# Or use Claude:
gid --provider claude
```

You can also choose a project explicitly:

```sh
gid --cwd ~/projects/my-project
```

Replace `my-project` with your actual project. Describe the task and expected behavior, attach relevant files with `@`, and review proposed actions before approving them.

| Control | Action |
| --- | --- |
| `Ctrl+J` | New line |
| `Enter` | Send |
| `Ctrl+Y` / `Ctrl+N` | Approve / deny |
| `Esc` | Cancel |
| `Alt+D` or `/diff` | Review changes |
| `/model` | Choose a model |
| `r` in the model list | Refresh models |
| `s` in the model list | Save the default |
| `gid --continue` | Resume the latest saved conversation |

Model discovery uses the official CLIs. An open model list refreshes every 15 minutes. New models do not change your current selection or saved default. If discovery fails, gid keeps the last successful list. Available models still depend on your account and the CLI version; update the official CLI when its model list is old.

## 4. Start gdm

Check your environment:

```sh
gdm --help
gdm doctor
```

With gdm skills installed, open a new Codex or Claude session in your project and make a request:

In Codex:

```text
$gdm-go Fix the login error and verify the result
```

In Claude Code:

```text
/gdm-go Fix the login error and verify the result
```

For Pi, install Pi separately and start it with `gdm-pi`. gdm records requirements, real check output, exit codes, and evidence hashes. Completing verification does not grant permission to commit, open a PR, or merge.

## 5. Connect your iPhone

Download [gdmux from the App Store](https://apps.apple.com/app/id6812978388) on iOS 17 or later. The current App Store version has partial English support. Full English localization and an in-app language selector are planned for the next update.

On your Mac, run:

```sh
gdmux --remote
```

Follow the account and Mac pairing steps. Use the same account in the iPhone app. Your Mac and its connection service must stay on and online. You can also open remote settings with **Ctrl+B**, then **m**, inside gdmux.

To create gid tasks from your iPhone, install gid on the Mac at `~/.local/bin/gid`. You can check tasks, send follow-up instructions, review requests, and approve actions.

## Interface language

The Mac tools start in Korean when your system language is Korean, and English otherwise. You can save a manual choice. Interface language does not translate terminal output, source files, saved conversations, or AI responses.

- **gdmux:** press **Ctrl+B**, then **p**, search `language`, and choose **Language: English**, **Language: 한국어**, or **Language: Auto / 자동**. The choice applies immediately and is saved. In `~/.config/gdmux/config.toml`, the top-level `language` value accepts `"en"`, `"ko"`, or `"auto"`.
- **gid:** enter `/language en` or `/language ko` to save a preference. `/language auto` removes the fixed choice. The personal setting is `ui.language` in `~/.config/gid/config.json`.
- **gdm:** run `gdm language en` or `gdm language ko` to save a preference. `gdm language auto` restores automatic selection.

To choose English for one launch only:

```sh
gdmux --language en
gid --language en
gdm --language en --help
```

You can also use `GDMUX_LANGUAGE=en`, `GID_LANGUAGE=en`, or `GDM_LANGUAGE=en` for a process. Open the globe button at the top of the website, then choose 한국어 or English. The language menu preserves your page, tool selection, and location. A shared `/en/` URL always opens in English.

## Themes

New installations use Tokyo Night. Existing theme choices are preserved. Personal theme settings live in `~/.config/gdmux/config.toml` and `~/.config/gid/config.json`. A project’s `.gid/settings.json` can override gid’s personal settings. Back up your config and merge specific settings instead of replacing the whole file.

See the optional [Black Glass theme guide](https://gdmux.pages.dev/themes/black-glass/README.en.md). Transparency requires a terminal that supports it. The website’s product screenshots currently show the Korean interface with example data.

## Updating

Run the same installer again with your chosen tools. Unselected tools stay as they are, and your personal settings are preserved. The installer does not stop running tasks. After finishing your work, close every gdmux session and restart gdmux so the background program uses the new version.

## Removing tools

These commands remove executables from the default location. Run only the command for the tools you actually want to remove:

```sh
# gdmux and its supporting executables:
rm ~/.local/bin/gdmux ~/.local/bin/gdmuxd ~/.local/bin/gdmuxctl ~/.local/bin/gdmux-remote

# gid only:
rm ~/.local/bin/gid

# gdm only:
rm ~/.local/bin/gdm
```

Work records, conversations, account settings, and separately installed skills remain. To remove gdm skills too, first disable the gdm hook in your AI agent configuration, then remove that agent’s `gdm-*` skills. Keep unrelated hooks intact.

## Need help?

- [Installation and FAQ](https://gdmux.pages.dev/en/start/#questions)
- [Support](https://15.165.211.112/support)

The source repository is private. Public Windows and Linux installers are not available yet.