<!-- Markdown mirror. Canonical: https://empryo.com/docs/tools/addons -->

# Addons

> Install Empryo's optional addons from the command line: a local proxy for chat subscriptions, and a bundled Neovim for the editor panel.

Addons are optional extras that are not part of the main download. You install them only if you want what they add, and you manage them with `empryo addon`.

There are two addons today. Neither is required, and a fresh install includes neither.

| Addon | What it adds |
|-------|--------------|
| `proxy` | [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI), a local relay that lets you use an existing Claude, ChatGPT, Gemini or Grok chat subscription instead of an API key. Use at your own risk; see [Proxy](/docs/providers/proxy). |
| `neovim` | A Neovim binary for the [editor panel](/docs/tools/editor), so you don't have to install Neovim yourself. |

## The first-run prompt

The first time you start Empryo in an interactive terminal, it asks whether you want either addon. Whatever you answer, it won't ask again.

The prompt is skipped when the terminal is not interactive (CI, pipes) or in headless runs. To skip it explicitly:

```bash
EMPRYO_NO_PROMPT=1 empryo
```

## Manage addons

```bash
empryo addon list                       # installed or not, version, path
empryo addon install proxy              # install the proxy addon
empryo addon install neovim             # install Neovim
empryo addon update neovim              # reinstall the latest version
empryo addon remove proxy               # uninstall
empryo addon setup                      # show the first-run prompt again
empryo addon --help                     # full usage
```

`empryo --addon …` works the same as `empryo addon …`. For listing, `list`, `ls`, `--list` and `-l` are interchangeable.

## Where files go

| Path | What |
|------|------|
| `~/.empryo/bin/` | The `cli-proxy-api` and `nvim` binaries Empryo runs |
| `~/.empryo/installs/` | One folder per installed version |

On Windows these live under `%LOCALAPPDATA%\Empryo`.

Empryo records what it installed under `addons` in `~/.empryo/config.json`:

```json
{
  "addons": {
    "proxy":  { "installed": true, "version": "1.4.2", "installedAt": "2025-01-15T12:00:00Z" },
    "neovim": { "installed": true, "installedAt": "2025-01-15T12:00:00Z" }
  }
}
```

## If you already have the binary

If `cli-proxy-api` or `nvim` is already on your `PATH` (from Homebrew, apt, scoop and so on), Empryo uses it and you don't need the addon.

If you install the addon anyway, Empryo keeps its own copy in `~/.empryo/bin` so a later `PATH` change can't break it. `addon remove` only deletes that copy. It never touches your system install.

## SoulStack

[SoulStack](https://github.com/proxysoul/SoulStack) is ProxySoul's set of skills, immune cells and working takeaways. Empryo doesn't turn it on by itself. Nothing changes until you install it.

Empryo finds a copy you already have: `SOULSTACK_DIR`, `soulstack.dir` in the global config, the checkout behind the `soulstack` command, or `~/dev/SoulStack`. Installing runs SoulStack's own setup script, which links its skills into `~/.agents/skills` and adds the takeaways to `~/.empryo/EMPRYO.md` inside a marked block. Your own rules stay.

```bash
empryo soulstack              # what's installed, where, and whether an update is out
empryo soulstack install      # set it up (clones to ~/dev/SoulStack when there is no copy)
empryo soulstack check        # look for an update, change nothing
empryo soulstack update       # get the latest and set it up again
empryo soulstack remove       # take it out again
empryo soulstack auto off     # stop the daily update
```

Once it's installed, the desktop app and the terminal check GitHub once a day and update it on their own. You can turn that off with `soulstack.autoUpdate`. In the terminal the same commands are under `/soulstack`. On desktop they're in Settings, under Add-ons.

## Environment variables

| Variable | What it does |
|----------|--------------|
| `EMPRYO_AUTO_INSTALL_ADDONS` | Install these addons automatically at startup, comma-separated (`proxy,neovim`). Handy in Docker images and CI. |
| `EMPRYO_PROXY_VERSION` | Install a specific CLIProxyAPI version instead of the default. |
| `EMPRYO_NO_PROMPT` | Set to `1` to skip the first-run prompt. |

## Proxy quickstart

> **Warning:**
> **Use at your own risk.** The relay sends your consumer subscription credentials to endpoints built for the vendor's own apps. Empryo is not affiliated with Anthropic, OpenAI, Google or xAI. Whether your plan allows this is between you and your provider. Rate limits, revoked credentials or a suspended account are possible. Details in [Proxy](/docs/providers/proxy).

```bash
empryo addon install proxy
empryo                # then, inside the terminal UI:
/proxy login          # add a Claude, ChatGPT, Gemini or Grok subscription
/proxy status         # see which accounts are active
/proxy quota          # see how much of each plan is left
```

Once an account is added, its models show up in `/models`. [Proxy](/docs/providers/proxy) explains how to read the quota meters, including the weekly per-model limits Claude applies on top of the account-wide ones.