---
name: dual-grok-account
description: >
  Configure a second Grok Build account on this machine using GROK_HOME so
  personal and work logins can run side by side without sharing auth.json.
  Use when the user wants two Grok accounts, work vs personal Grok Build,
  dual login, multi-account setup, GROK_HOME isolation, or runs /dual-grok-account.
metadata:
  short-description: "Second Grok Build account via GROK_HOME"
---

# Dual Grok Build account setup

Set up a second Grok Build home directory so two accounts can run at the same time without overwriting each other.

## What matters

- Default state lives under `~/.grok` (auth, config, sessions).
- Auth is stored in `$GROK_HOME/auth.json` (default `~/.grok/auth.json`).
- `grok login` rewrites that file. Grok hot-reloads it, so shared homes bleed credentials across terminals.
- `GROK_HOME` overrides the entire config directory. That is the isolation boundary.
- Session tokens beat `XAI_API_KEY`. The API key only applies when no session is active in that home.
- Never copy `auth.json` between homes. Copying `config.toml` is fine.

## Workflow

### 1. Confirm intent

Ask only what you need:

- Label for the second account (default: `work`)
- Path for the second home (default: `~/.grok-work`)
- Whether to copy `config.toml` from the primary home (default: yes if primary exists)
- Whether to install shell aliases (default: yes)

Do not ask about terminal apps. Ghostty vs Terminal does not isolate accounts by itself.

### 2. Create the second home

```bash
mkdir -p "$SECOND_HOME"
```

If copying config:

```bash
if [ -f "$HOME/.grok/config.toml" ]; then
  cp "$HOME/.grok/config.toml" "$SECOND_HOME/config.toml"
fi
```

Never copy `auth.json`, `sessions/`, or credential files.

### 3. Install aliases (optional)

Append to the user's shell rc if the aliases are not already present. Prefer `~/.zshrc` on macOS zsh.

```bash
# Grok Build multi-account
alias grok-personal='GROK_HOME="$HOME/.grok" grok'
alias grok-work='GROK_HOME="$HOME/.grok-work" grok'
```

If the second home is not `~/.grok-work`, adjust the alias name and path to match the label they chose.

After editing, tell them to `source ~/.zshrc` or open a new shell.

### 4. Login instructions

Do not run browser login for them unless they explicitly ask. Print the exact command:

```bash
GROK_HOME="$SECOND_HOME" grok login
```

Then:

```bash
GROK_HOME="$SECOND_HOME" grok
```

Or the alias, e.g. `grok-work`.

Primary account keeps using default `grok` / `~/.grok`.

### 5. Optional: pin one terminal profile

If they use Ghostty (or another terminal with profile env vars), they can set `GROK_HOME` on one profile so that window is always the second account. Mention this only if relevant. Do not edit terminal config unless they ask.

### 6. Verify

Check without dumping secrets:

```bash
test -d "$HOME/.grok" && echo "primary home: ok"
test -d "$SECOND_HOME" && echo "second home: ok"
test -f "$SECOND_HOME/auth.json" && echo "second auth: present" || echo "second auth: missing (run login)"
```

Remind them: skills, MCP config, and sessions are per-home unless copied or reconfigured.

## Failure modes

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| Both terminals on same account | Same `GROK_HOME` / default home | Export different `GROK_HOME` per process |
| Login in one flips the other | Shared `auth.json` | Separate homes; never share auth |
| API key ignored | Active session in that home | Use clean home, or log out / remove session for that home |
| Skills missing in work | Skills live under that home | Copy skills dir, reinstall, or use primary for shared skills |

## Done criteria

- Second home directory exists
- Aliases installed (if requested)
- User has the exact login command for the second account
- Clear which command is personal vs work