CLI agent not found

Spawn fails with spawn_failed + code=cli_not_found. The agent ran your login shell (bash -lc 'claude' or equivalent) and the shell couldn't resolve the binary.

1. Verify the CLI is installed for the right OS user

A common gotcha on multi-user hosts: the CLI is installed for root (the daemon) but not for alice (the user the workspace runs as). Qorin uses the workspace owner's PATH, not root's.

Test from the host, as the workspace owner:

# on the host, in the right user's shell:
su - alice                      # or login as alice
which claude codex cursor-agent gemini opencode

If which returns nothing for the CLI you picked, install it for that user.

Qorin invokes the CLI through <user-shell> -lc '<cli>' where <user-shell> is the shell defined in /etc/passwd for the user (Linux) or dscl . -read /Users/alice UserShell (macOS). If the shell is /usr/sbin/nologin or /bin/false, spawn will fail — change to /bin/zsh or /bin/bash.

# Linux: change shell for alice
sudo chsh -s /bin/bash alice

3. Look at the agent journal

It logs the exact command + the exit reason:

sudo journalctl -u qorin-agent -n 200 --no-pager | grep -A2 spawn

Look for exit status lines after the spawn command.

4. PATH not loaded

The shell loads .bashrc/.zshrc only in interactive sessions; -lc should also load .bash_profile / .zprofile. If you have a tool like mise, asdf, volta, nvm that injects PATH from a non-standard file, make sure it's sourced from .zprofile / .bash_profile, not just .zshrc / .bashrc.

Quick test as the target user:

bash -lc 'which claude'

If this prints nothing but bash -ic 'which claude' works, PATH injection happens in .bashrc (interactive only). Move it to .bash_profile.

5. The CLI is on Homebrew

Homebrew on Apple Silicon installs to /opt/homebrew/bin which isn't in the default root PATH. Qorin runs through the user's login shell, so this works — but only if the user's login shell has eval "$(/opt/homebrew/bin/brew shellenv)" in .zprofile. Fresh macOS installs ship this; if you migrated from an older Mac you may need to add it.

6. opencode installs outside the default PATH

opencode's own installer puts the binary at ~/.opencode/bin/opencode — a directory no shell has on its PATH out of the box. The installer adds a line to a shell profile for you; if that line landed in .zshrc / .bashrc (interactive shells only), section 4 above applies verbatim and you'll see cli_not_found even though opencode works fine when you type it yourself.

Test it the way Qorin does — through a login shell, as the workspace's OS user:

bash -lc 'which opencode'      # or: zsh -lc 'which opencode'

If that prints nothing, add the directory to .zprofile / .bash_profile:

export PATH="$HOME/.opencode/bin:$PATH"

CLI agent not found ​

1. Verify the CLI is installed for the right OS user ​

2. Check the login shell ​

3. Look at the agent journal ​

4. PATH not loaded ​

5. The CLI is on Homebrew ​

6. opencode installs outside the default PATH ​

See also ​