codex-muse

# codex-muse

> Unofficial community project. Not affiliated with, sponsored, or endorsed by
> Meta or OpenAI. You need your own Meta Muse access (a Meta account entitled
> to Muse); the login helper signs in through Meta's device-code flow and
> stores the resulting credential locally.

Installer for the `muse` [Codex](https://developers.openai.com/codex) profile
plus three helper binaries — no `muse` binary required.

After installing you can run:

```sh
codex --profile muse exec "say hi"
codex-muse-login     # sign in (Meta device-code flow, opens a browser link)
codex-muse-usage     # subscription usage: 5h window + weekly
codex-muse-logout    # sign out
```

Works on Linux and macOS.

## Install

```sh
git clone https://github.com/kengzzzz/codex-muse codex-muse
cd codex-muse
./install.sh
```

Useful options:

```sh
./install.sh --bin-dir ~/.local/bin --codex-home ~/.codex
./install.sh --force        # overwrite without keeping .bak backups
./install.sh --no-verify    # skip post-install checks
./install.sh --uninstall            # remove profile + binaries (keeps login)
./install.sh --uninstall --purge    # also delete the saved login
```

`BIN_DIR` and `CODEX_HOME` environment variables are respected as defaults
when the matching flags are not given.

### What it installs

| Source in this repo | Installed to |
|---|---|
| `profile/muse.config.toml` (+ substituted paths) | `$CODEX_HOME/muse.config.toml` |
| `profile/muse-model-catalog.json` | `$CODEX_HOME/muse-model-catalog.json` |
| `bin/codex-muse-login` | `$BIN_DIR/codex-muse-login` |
| `bin/codex-muse-logout` | `$BIN_DIR/codex-muse-logout` |
| `bin/codex-muse-usage` | `$BIN_DIR/codex-muse-usage` |

Re-running the installer is safe: identical files are left alone, changed
files are backed up to `*.bak.<timestamp>` (unless `--force`).

### Requirements

The installer itself only needs stock tools (`bash`, `mkdir`, `cp`, `chmod`,
`cmp`, `sed`, `grep`). The helpers need `curl` and `jq` at runtime
(macOS: `brew install curl jq`), plus the `codex` CLI. Missing pieces
produce warnings, not failures.

If `$BIN_DIR` is not on your `PATH`, the installer tells you the export line
to add. On macOS, `~/.local/bin` is not on `PATH` by default — add it to
`~/.zshrc` / `~/.zprofile` (zsh) or `~/.bash_profile` (bash).

## Usage notes

- Login credentials live in `${CODEX_HOME:-~/.codex}/muse-auth.json`
  (`MUSE_AUT