Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Backend Lifecycle Chip Plan
Background
The Settings → Backends page currently shows a tiny "Found" / "Missing" pill per backend (AgentDetection.tsx → StatusBadge). It cannot tell the user:
- whether the installed CLI is up to date
- whether the backend's persistent server process (OpenCode / Codex) needs a restart to pick up a new Provider / MCP / env change
- how to recover when a backend isn't running
The unified design.pen (qUpin / NrTO1 / x53H1P) replaces that pill with a chip + popover. The popover surfaces five visual states (Ready / Updating / Disabled / Error / Update Available) and the small set of operations the user is allowed to perform.
Goal
Wire the Settings → Backends chip + popover to live backend state and provide three user-facing operations:
- Upgrade — for all three backends (Claude / OpenCode / Codex), re-run the installer to pull the latest CLI release.
- Restart — only for OpenCode and Codex (persistent server processes). Used after Provider / MCP / env config changes. Claude is a one-shot CLI so this action is hidden.
- Reinstall — when the backend's CLI is missing or fails to start, run the installer.
Out of scope:
- Stop / Start buttons. The user explicitly said Vibe Remote should manage these processes; only Restart is exposed.
- PID / uptime / exit code / auto-restart timers. None of this leaks into the UI.
- Per-cwd restart granularity for Codex. Restart resets all in-process Codex transports.
Solution
Process-model reminder
- OpenCode — singleton server (
OpenCodeServerManager), lazy-started on first message, PID persisted to~/.vibe_remote/logs/opencode_server.json. UI server can kill it via the existing pid-file path (same pattern asvibe/cli.py::_stop_opencode_server). - Codex — one persistent
codex app-serversubprocess per working directory, held in-memory insideCodexAgent._transports. No pid file. UI server enumeratescodex app-serverprocesses owned by the current user and sends SIGTERM; the controller's lazy-start path respawns on the next message. - Claude — one-shot CLI invocation per request; no daemon, no restart action.
Backend (Python)
vibe/api.pyget_backend_runtime(name)returns{ "name": "opencode" | "claude" | "codex", "enabled": bool, # from config "cli_path": str, # configured path "installed": bool, # resolves on PATH "current_version": str | None, # `<cli> --version`, 5s timeout, 30s cache "latest_version": str | None, # registry probe, 1h cache, best-effort "has_update": bool, "supports_restart": bool, # True for opencode / codex "process_status": "running" | "stopped" | "unknown", "error": str | None, }restart_backend(name)→{ok, message}. Reuses_stop_opencode_server-style pid-file kill for OpenCode; enumeratescodex app-serverprocesses viapsutilfor Codex; returns{ok: False, message: "..."}for Claude.- Upgrade reuses
install_agent(name)(already runs the upstream installer; same code path for install + upgrade). - Caching uses two TTL dicts at module scope (
_VERSION_CACHE,_LATEST_CACHE), guarded by short timeouts and clean fallback (latest_version=None, has_update=False) on network failure.
vibe/ui_server.pyGET /backend/<name>/runtime→ returnsapi.get_backend_runtime(name).POST /backend/<name>/restart→ returnsapi.restart_backend(name). Allowlists{opencode, codex}.- Upgrade keeps using existing
POST /agent/<name>/install.
Frontend
ui/src/components/settings/BackendLifecycleChip.tsx(new)- Props:
{ name, enabled, cliStatus, onUpgraded? }. - Owns its own popover state, version probe (lazy via
api.getBackendRuntime), upgrade + restart calls. - Visual state derivation (priority order):
enabled === false→ Disabled (muted)- internal
phase === 'upgrading'→ Updating (cyan) cliStatus === 'missing'orruntime.installed === false→ Error / Not running (red)runtime.has_update→ Update available (amber)- else → Ready (mint)
- Popover footer:
- Update available →
Upgradebutton. - Ready →
Restartbutton only whenruntime.supports_restart(i.e. opencode / codex). - Error →
Restart(when supported) +Reinstallbuttons. - Disabled → muted hint, no buttons.
- Updating → progress, no buttons.
- Update available →
- Disable the Restart button if the backend is currently upgrading.
- Props:
ui/src/context/ApiContext.tsx- Add
getBackendRuntime(name)andrestartBackend(name)with typed return shapes.
- Add
ui/src/components/steps/AgentDetection.tsx- Replace
<StatusBadge>with<BackendLifecycleChip>inside each backend card header. - Keep the existing first-time install hint (
isMissing(agent)block) so the Setup Wizard's first-run guidance remains inline; the chip handles ongoing lifecycle.
- Replace
i18n: add
backendLifecycle.*keys inui/src/i18n/en.json+ui/src/i18n/zh.json.
Latest-version sources
- OpenCode —
https://api.github.com/repos/sst/opencode/releases/latest→tag_name(strip leadingv). - Codex —
https://registry.npmjs.org/@openai/codex/latest→version. - Claude —
https://registry.npmjs.org/@anthropic-ai/claude-code/latest→version.
All probes use a 5s timeout and short-circuit to latest_version=None on any error; the chip silently falls back to Ready instead of Update available in that case.
TODO
- Plan document.
- Implement
api.get_backend_runtime+ cache + version probes. - Implement
api.restart_backend— controller IPC via marker file~/.vibe_remote/state/runtime_commands/restart-<backend>.cmd, with UI-side direct-kill fallback when the controller doesn't ack within 4s. - Wire HTTP routes
GET /backend/<name>/runtime+POST /backend/<name>/restart. - Add
getBackendRuntime/restartBackendtoApiContext. - Build
BackendLifecycleChip+ popover. - Swap into
AgentDetection.tsx. - i18n strings for both languages.
-
npm run buildinui/, fix typescript / lint warnings. -
ruff checkon touched Python files. - Reviewer subagent + manual sanity check.
Implementation notes (delta vs original plan)
- Restart is not a direct UI-side kill anymore. The UI server writes a marker file and the controller's
RuntimeCommandWatcherrunsagent_auth_service._refresh_backend_runtime(backend)— the existing controller-side cleanup that already covers Codex transports + OpenCode singleton, so cached state in the controller process stays consistent. Direct kill remains only as a fallback after a 4 s ack timeout. packaging>=23.0was added as a runtime dependency for proper PEP 440 version comparison; a tuple-based fallback handles parses thatpackaging.version.Versionrejects.- Failed
latest_versionprobes are cached for 120 s (vs 3600 s for success) so transient outages don't lock in a stale "no update" reading for an hour. - All version + latest caches are keyed by
(name, cli_path)so editing the configured CLI path invalidates the cache.
Evidence
- Unit: add focused pytest for version-string parsing +
restart_backendClaude-path no-op. - Contract:
psutillookup is best-effort; no scenario catalog entry needed. - Manual: in local Incus regression, open Settings → Backends, verify each chip renders the right state for installed / missing / disabled and that Upgrade + Restart succeed.