# Claude Code or agent CLI not found on Omarchy
Why claude, codex, gh and other mise-backed agent CLIs go missing, hang forever, or print junk on Omarchy 4, and how to rebuild the stubs and fix PATH.
> **Short answer:** On Omarchy 4 the agent CLIs are not packages. They are tiny mise stubs in ~/.local/bin written by omarchy-mise-install. If claude or codex is not found, run omarchy refresh applications to rewrite every stub, then open a new shell. If the command is found but hangs forever, your PATH puts ~/.local/bin ahead of the mise shims, which makes the stub exec itself.
- Applies to Omarchy: 4.0.0 and later
- Status: workaround
- Last verified: 2026-09-16
- Canonical: https://omarchylinux.org/fix/claude-code-or-agent-cli-not-found/
_Unofficial community page. Not affiliated with 37signals or the Omacom Foundation. Omarchy is a registered trademark of 37signals LLC._

On Omarchy 4 the coding agents are not packages. `claude`, `codex`, `opencode`, `gemini`, `copilot`, `crush`, `grok`, `pi`, `omp`, `gh` and the rest are small bash stubs in `~/.local/bin`, each written by `omarchy-mise-install` and each backed by [mise](https://mise.jdx.dev/). That is why "not found" and "found but broken" have completely different causes here. Checked against v4.0.0 through v4.0.4.

## The fix

Work through these in order. Everything below is for Omarchy 4.x; 3.x is at the end.

1. Find out what the shell actually resolves.

   ```bash
   type -a claude
   ls -l ~/.local/bin/claude
   ```

   A stub is a regular file starting with `#!/bin/bash` and containing `mise use -g --quiet`.

2. If the stub is missing, rewrite every stub at once:

   ```bash
   omarchy refresh applications
   ```

   That runs `install/user/mise.sh`, which calls `omarchy-mise-install` for each shipped tool. For a single tool: `omarchy-mise-install claude`. For a tool with a non-default backend, pass the package first, for example `omarchy-mise-install npm:@xai-official/grok grok`.

3. Open a new shell, or reload PATH in the current one:

   ```bash
   exec bash -l
   ```

   `~/.local/bin` and `~/.local/share/mise/shims` are appended to PATH by `default/bash/env-bootstrap`, which the login profile, `/etc/skel/.bashrc` and the uwsm session all source. If you never get a login shell, that bootstrap never runs.

4. If the command is found but hangs forever, check PATH order. This is the exec loop. The 4.0.4 stub template still has it, and the fix in PR #9175 is open and unmerged:

   ```bash
   printf '%s\n' "$PATH" | tr : '\n' | grep -n 'local/bin\|mise/shims'
   ```

   If the `.local/bin` line number is lower than the `mise/shims` line, the stub shadows the real binary and execs itself. Fix the thing that prepends `~/.local/bin`. The common offender is the `uv` installer's env snippet in `~/.bashrc`, which prepends `$HOME/.local/share/../bin`. That path resolves to `~/.local/bin`, but because the string differs, the snippet's own "already on PATH" check does not catch it. Remove that line, or move it above Omarchy's own bootstrap so the shims stay in front.

   To get work done right now without touching your rc files, bypass the stub:

   ```bash
   mise x claude -- "$(mise which claude)"
   ```

5. If the stub runs but its output is corrupted, it predates the `--quiet` flag that landed in 4.0.1. Symptoms are a `mise ~/.config/mise/config.toml tools: gh@...` banner on stdout, and for `gh` a git push that dies with `warning: invalid credential line`. Regenerate it:

   ```bash
   omarchy-mise-install gh
   omarchy-mise-install claude
   ```

   Nothing regenerates these automatically. The bulk regeneration migration parses an older wrapper format and silently skips every current stub.

6. If the launcher says `claude is not installed. Choose an installed agent with: omarchy default agent <name>`, you have no default agent recorded, or the recorded one has no command. Set it:

   ```bash
   omarchy default agent claude
   ```

   This writes `~/.config/omarchy/defaults/agent` and installs the tool through mise if it is not there. `omarchy agent` then launches it; `Super + Shift + Ctrl + A` and the `a` alias both go through the same path.

7. If picking the default agent installs an older build than the one you already had, defeat mise's release cooldown by hand:

   ```bash
   MISE_MINIMUM_RELEASE_AGE=0 mise use -g claude
   ```

   `omarchy-default-agent` is the one place that does not set that variable. The stubs, `omarchy-update-mise` and the `mup` alias all do.

On 3.x this page mostly does not apply. Omarchy 3.8.4 shipped `claude-code` as a pacman package in `install/omarchy-base.packages`, there was no `omarchy-agent`, no default-agent picker and no `~/.local/bin` stub. If `claude` is missing on 3.x, reinstall the package. The switch to mise stubs happened in 4.0.0.

## Verify it worked

```bash
type -a claude          # ~/.local/bin/claude first, then the mise shim
timeout 60 claude --version
mise which claude       # absolute path inside ~/.local/share/mise/installs
claude --version 2>/dev/null | head -1   # no mise banner on stdout
omarchy default agent   # prints the recorded default, empty if none
```

`claude --version` should return in seconds. If it is still running after a minute, you are in the exec loop, not a slow download.

## Why it happens

`omarchy-mise-install` writes a stub of this shape:

```bash
#!/bin/bash
export MISE_MINIMUM_RELEASE_AGE=0
mise use -g --quiet "claude" || exit 1
exec mise x "claude" -- "claude" "$@"
```

The last line hands `mise x` a bare command name. `mise x` resolves that name through PATH, and how it builds that PATH is the whole story. smartpbx worked out the rule on issue #7360 and guruthechosen confirmed it. With no shims directory on PATH, mise puts the tool's install directory at the very front, and the stub can never win. With the shims directory present, mise slots the install directory in just ahead of it and does not touch anything earlier. So if `~/.local/bin` sits ahead of the shims, the stub finds itself, execs itself, and never returns. `exec` keeps it in one PID, so `ps` shows a single command burning a core rather than an obvious fork bomb.

A stock install does not trip this: `env-bootstrap` appends the shims directory first and `~/.local/bin` after it, so the order mise needs is already there. Something else has to push `~/.local/bin` to the front, which is why the loop shows up for some people and not others on identical releases.

Two other paths lead to the same symptom. `omarchy-mise-install` runs `rm -f` on the target before writing, so a hand-written wrapper you put at one of those names is deleted without a prompt when the stubs are refreshed. And a stale mise registry can make the install itself fail, which leaves you with a stub and no binary behind it; that is what the OpenCode and `gh` reports on 4.0.0 turned out to be, cleared by updating mise rather than by any Omarchy change.

## If that did not work

- npm-backed agents need the mise environment, not just the path. Running `"$(mise which grok)"` directly can fail with `exec: node: not found`, because the npm shim's fallback is a bare `exec node`. Always keep `mise x` in the chain.
- If `omarchy default agent` prints `Could not install Claude Code with mise`, run `mise use -g claude` by hand and read the full error. A stale registry or a failed attestation shows up there and nowhere else.
- Update mise itself before blaming Omarchy: `sudo pacman -Syu mise-bin`. Omarchy 4.0.1 swapped Arch's `mise` for the `mise-bin` package from its own repo (migration 1786952219).
- If you removed the preinstalls, `~/.local/state/omarchy/preinstalls-removed` exists and several migrations deliberately skip writing stubs for you. Install what you want by hand with `omarchy-mise-install`.
- A wrapper of your own that was overwritten is probably gone for good. Omarchy configures snapper for the root subvolume only, so pre-update snapshots do not cover `/home`.

Evidence on the exec loop is strong and current: three separate open reports filed on 4.0.0 and 4.0.1, a confirmation on 4.0.3, matching reproductions in each, and an unmerged PR (#9175) that changes the stub template. Evidence on how often the stub simply goes missing is thinner, and mostly reaches the tracker as a side effect of the other bugs.

## Related

- [mise command not found or shims](/fix/mise-command-not-found-or-shims/)
- [Codex invalid value for --ask-for-approval](/fix/codex-invalid-value-ask-for-approval/)
- [omarchy update fails or hangs](/fix/omarchy-update-fails-or-hangs/)
- [Upgrading 3 to 4](/upgrade/3-to-4-quattro/)
- The official manual chapter: [omarchy.org/manual/ai/](https://omarchy.org/manual/ai/)

## Sources

- [Issue #6349: omarchy-mise-install wrappers infinite-loop when mise's PATH hook isn't active (related #3685)](https://github.com/omacom/omarchy/issues/6349)
- [PR #6350: Fix infinite loop in omarchy-mise-install wrappers](https://github.com/omacom/omarchy/pull/6350)
- [Issue #7360: mise tool wrappers can exec themselves forever: `mise x <pkg> -- <bin>` resolves <bin> back to the wrapper](https://github.com/omacom/omarchy/issues/7360)
- [Issue #7234: mise wrappers still exec-loop when mise x falls back to a PATH lookup (residual case of #6349)](https://github.com/omacom/omarchy/issues/7234)
- [Issue #8990: omarchy-mise-install generates wrappers that recurse through PATH and hang](https://github.com/omacom/omarchy/issues/8990)
- [PR #9175: Stop mise wrappers from re-executing themselves (breaks Claude Code detection in T3 Code)](https://github.com/omacom/omarchy/pull/9175)
- [Issue #11971: mise wrappers made before --quiet pollute stdout, and the regeneration migration can no longer parse them](https://github.com/omacom/omarchy/issues/11971)
- [PR #6940: Keep mise wrappers from writing to stdout](https://github.com/omacom/omarchy/pull/6940)
- [Issue #8253: Selecting the default agent installs an older version than the one already installed](https://github.com/omacom/omarchy/issues/8253)
- [Issue #7101: omarchy update destroys user binaries in ~/.local/bin at 13 fixed names, including gh and claude](https://github.com/omacom/omarchy/issues/7101)
- [Issue #6886: Agent setup for OpenCode fails on Quattro: mise resolves to deprecated aqua:sst/opencode](https://github.com/omacom/omarchy/issues/6886)
- [Issue #6887: Any mise-wrapped tool hits broken aqua attestations: gh wrapper fails on Quattro (affects omarchy-mise-install defaults)](https://github.com/omacom/omarchy/issues/6887)
- [Omarchy manual: AI](https://omarchy.org/manual/ai/)
- [Omarchy v4.0.0 release notes](https://github.com/omacom/omarchy/releases/tag/v4.0.0)