What is opencues run?

opencues run <host> launches a patched host (opencues run claude-code, opencues run opencode, opencues run gemini-cli) so you never have to remember where each patched binary lives.

What it does beyond exec

On paper it's a convenience wrapper that execs the right binary. In practice it does two other things that make it the recommended launch path:

• Orphan cleanup. Every run starts by reaping leaked processes from prior invocations of the same host (terminals close, wrappers die, processes double-fork), the same check opencues cleanup runs standalone.
• Self-healing installs. Before spawning the host, it compares a hash of the current runtime source against the hash recorded when the host's bundle was installed. If they differ, it transparently re-runs the installer first, with one info line telling you why (bundle is stale ... Rebuilding before launch). Pass --no-rebuild-check to skip.

Why the drift check exists

The bundled runtime inside a patched host doesn't update itself when you pull new source. Before the self-heal shipped, a stale install could silently run weeks-old code while the repo looked current, which produced exactly the confusing "I fixed it but nothing changed" sessions you'd expect. The hash fires on any source byte change, so forgetting a version bump can't mask drift.

When to bypass it

You can always invoke the patched binaries directly; they work. You just skip the cleanup and the drift check, so direct launches are best when you know the install is fresh. If OpenCues seems dead after a git pull, the first fix is simply launching through opencues run again.

Related: How to update OpenCues · opencues doctor · How to install · GitHub repo