Problem
Codex sessions launched directly inside tmux can be non-native / not daemon-backed if the user's shell has not loaded Hive's shell integration:
eval "$(hive shell-init zsh)"
When this is missing, commands such as hive team fail with the degraded-runtime message and ask the user to add the shell-init snippet manually, then restart via hive codex resume.
This is correct as a recovery path, but the user only learns about it after hitting the degraded state.
Desired behavior
Hive should detect this during install/update or the nearest practical post-install/update flow, and proactively tell the user what to add.
Candidate surfaces:
hive doctor: report whether the current shell startup file appears to load hive shell-init.
hive shell-init: document the exact persistent install command more prominently.
hive codex / degraded gate: keep the existing recovery message, but also point to the doctor/install check.
- install/update docs or plugin refresh flow: include a post-update check/reminder.
Caveat: pipx install / pipx upgrade may not provide a reliable hook to edit or inspect the user's shell startup files. If so, implement this as a Hive CLI / doctor / docs check rather than pretending install can always modify shell config.
Acceptance criteria
- A user who installs or updates Hive has a clear path to discover whether
eval "$(hive shell-init zsh)" or the equivalent for their shell is configured.
- The check does not silently edit shell startup files without explicit user action.
- The degraded Codex error remains actionable and points to the same canonical setup path.
- zsh is covered first; fish/bash can be added if supported by
hive shell-init.
Problem
Codex sessions launched directly inside tmux can be non-native / not daemon-backed if the user's shell has not loaded Hive's shell integration:
When this is missing, commands such as
hive teamfail with the degraded-runtime message and ask the user to add the shell-init snippet manually, then restart viahive codex resume.This is correct as a recovery path, but the user only learns about it after hitting the degraded state.
Desired behavior
Hive should detect this during install/update or the nearest practical post-install/update flow, and proactively tell the user what to add.
Candidate surfaces:
hive doctor: report whether the current shell startup file appears to loadhive shell-init.hive shell-init: document the exact persistent install command more prominently.hive codex/ degraded gate: keep the existing recovery message, but also point to the doctor/install check.Caveat:
pipx install/pipx upgrademay not provide a reliable hook to edit or inspect the user's shell startup files. If so, implement this as a Hive CLI / doctor / docs check rather than pretending install can always modify shell config.Acceptance criteria
eval "$(hive shell-init zsh)"or the equivalent for their shell is configured.hive shell-init.