Repository navigation
Closed
Labels
harnessneeds-triageMaintainer needs to evaluate this issueMaintainer needs to evaluate this issueresearchDefining or executing a research into an aspect: tech, direction, decisionDefining or executing a research into an aspect: tech, direction, decision
Milestone
Description
Question
What non-trivial things does ai-buddy need on top of the compiled binary just to run (Harness CLIs, npx, Node, platform webviews, portals, …)? For each one: can we make the ship self-contained (goal), or do we accept an outside dependency and list / present it elegantly so the user knows what to install (big compromise — never a silent failure)?
Why now
#726: landing “Codex” looked successful while the console said `npx` is not installed and Chat sat on codex - not running. That is the product shape of an undeclared runtime dep. Before we paper over one tool, inventory the whole set.
Scope
In
- Census — every runtime requirement beyond
ai-buddy(+ Characters assets that ship with us). At least:- Harness launch paths (Claude Code, Codex/
npx @agentclientprotocol/codex-acp, Grok, Hermes, OpenCode, Pi, …): which need a CLI onPATH, which need Node/npx, which need a login/session elsewhere. - Anything we shell out to for MCP adapters, updates, or packaging.
- Platform runtime we assume but do not bundle (WebView2 on Windows, WebKitGTK on Linux, etc.) if missing breaks a surface.
- Optional vs required for “Character alone / Model API / StaticDirector” vs “Harness Chat works”.
- Harness launch paths (Claude Code, Codex/
- Challenge each row — for every dep: keep / replace / vendor / document-only. Prefer self-contained when the cost is sane.
- Presentation — if a dep stays external: where the user learns it (landing, Settings, first failure), what exact install steps, and how Chat must fail loudly instead of bug(chat): Codex landing connect shows no error, chat header stuck on "codex - not running" #726’s silent path.
- Recommendation — ranked: (A) what we can eliminate or bundle for V1, (B) what we must declare, (C) what stays advanced/BYO.
Out
- Implementing the UX or bundling in this issue (follow-up tickets).
- Choosing a new Harness product line — only the shipping surface of deps we already support or plan.
Done when
- A table (or equivalent) of runtime deps: name, why needed, how detected today, required vs optional, self-contain options, recommend keep/bundle/declare. → PR spike(ship): Census of runtime deps beyond the binary #932 /
docs/research/runtime-dependencies.md - Explicit call on self-contained vs declare for
npx/Node and each Harness CLI path. - Sketch of failure UX when a declared dep is missing (no silent
*- not running). → fix(chat): Surface a missing Harness launcher on the landing #831 shipped; sticky inline locked (feat(ux): Sticky missing-dep failure (no auto-dismiss toast) #950). - Follow-up issues filed for anything we decide to build; this spike closes with the recommendation.
Decisions (Oded, 2026-09-23) — locked on #932
- Node/npx — not bundling. Graceful fail if missing. README lists as requirements for harnesses that need it. (spike(ship): Bundle Node runtime + pinned ACP adapters for self-contained Claude/Codex/Pi #928 closed not planned)
- Harness CLIs — not bundling. Graceful fail if missing. README lists PATH + auth requirements per harness usecase.
- WebView — as recommended. Graceful fail if missing. README (Tauri): Windows handled; Linux declare; macOS nothing.
- GStreamer — optional. README for Linux audio cues; nice-to-have.
- libfuse (Linux AppImage) — AppImage only. When shipping AppImage, prefer type 2 with bundled runtime.
- X11/Wayland — environment, not a dependency.
- MCP stdio binary — challenge why we still need it; do not bundle with main binary; optional download at best; HTTP+bearer primary.
- Failure UX — sticky inline (copy-pasteable into search/AI), not auto-dismiss toast; keep error until fixed / user acts. (feat(ux): Sticky missing-dep failure (no auto-dismiss toast) #950)
- Harness Apply/Connect — copy + chat "initializing…" until ACP ready (no premature failing turns). (fix(harness): Apply/Connect copy + chat "initializing…" until ACP ready #949)
- Presets — Goose now (feat(harness): Named preset for Goose (zero-npx, open-source local agent) #930); copilot not for now; antigravity + others V2 TBD.
- npx alternatives (first-party Claude/Codex ACP binaries) — V2 future spike.
- ADR — document self-contain vs declare framework + V1 calls. (docs(adr): Runtime dep philosophy — self-contain vs declare (V1 decisions) #948)
Follow-ups
| Issue | Status |
|---|---|
| #928 Node bundling spike | Closed not planned |
| #929 Settings/landing first-party vs npx + install URLs | Open |
| #930 Goose named preset | Open |
| #948 ADR runtime dep philosophy | Open |
| #949 Apply/Connect + initializing chat | Open |
| #950 Sticky inline missing-dep | Open |
| #932 Research note PR | Open — merge when tip records decisions |
Related
- bug(chat): Codex landing connect shows no error, chat header stuck on "codex - not running" #726 — Codex landing + missing
npx(motivating incident; closed by fix(chat): Surface a missing Harness launcher on the landing #831) - fix(chat): Surface a missing Harness launcher on the landing #831 — loud failure when launcher missing
- Attaching real harnesses: per-harness MCP client config for Claude Code, opencode, Hermes, Pi, and Grok #166 / spike(harness): Integrate and test OpenAI Codex CLI as a Harness (ACP?) #554 / spike(harness): How each Harness registers a BYO MCP server, and whether it can send a bearer token #580 / feat(settings): Generate the MCP registration for a Harness you run yourself #599 — Harness attach / Codex / BYO MCP (context, not dupes)
— Cursor agent (Architect), on @omesser's behalf.
Metadata
Metadata
Assignees
Labels
harnessneeds-triageMaintainer needs to evaluate this issueMaintainer needs to evaluate this issueresearchDefining or executing a research into an aspect: tech, direction, decisionDefining or executing a research into an aspect: tech, direction, decision
Projects
- StatusShow more project fieldsDone
Activity
omesser commentedon Sep 17, 2026
Spike note:
npxvsacpx(Architect, 2026-09-17)Feeds this census (#735). Motivating bug remains #726 (
npxmissing → silent Codex fail).What ai-buddy needs today
From
src-tauri/src/harness.rslaunch():npx/Node?claudenpx -y @agentclientprotocol/claude-agent-acp@latestcodexnpx -y @agentclientprotocol/codex-acp@latestpinpx -y pi-acp@latesthermeshermes acpopencodeopencode acpgrokgrok agent stdiocursor-agentcursor-agent acpSo
npxis not “on top of every harness” — it is specifically the Zed-registry ACP adapter path for Claude / Codex / Pi. First-party ACP harnesses already avoid it.What
acpxisacpxon npm (v0.17.x). Node ≥22.13. MIT (per package).npx -y @agentclientprotocol/…/npx pi-acp(docs/agents.md). Native agents (cursor-agent,grok, …) do not need npx — same split we already have.Conclusion: vendoring / sidecar-shipping
acpxdoes not remove the Node/npxdependency for Claude/Codex/Pi. It would add a second ACP client (and usually still need Node to runacpxitself) next to our Rust client.Options that actually address
npxRanked for V1 honesty:
hermes,opencode,grok,cursor-agent) where the user has them — already zero-npx. Product/UX, not shipping Node.npx/Node missing for Claude/Codex/Pi (fix bug(chat): Codex landing connect shows no error, chat header stuck on "codex - not running" #726 first). Accept external dep; never silent.node+ offlinenode_modulesfor the three packages (ornode path/to/cli.jsinstead ofnpx -y). Removes network/npxcold start; still ships Node (~50–100MB+). Update cadence and licenses become ours.acpxas the fix for npx. Wrong layer. Revisit only if we wanted its session/flow UX as a separate product surface (we do not; we are the client).claude acp/ official binary adapters if/when upstream ships them — then drop Zed npm adapters for those rows.Recommendation for this census
acpx: not a self-contain path for V1. Document as “looked at; wrong layer.”npx/Node: for Claude/Codex/Pi rows → declare (install Node + ensurenpxon PATH) until/unless we deliberately take option 3.claude-agent-acp/codex-acp/pi-acp” with size/license table; (c) Settings/landing copy that distinguishes first-party ACP vs npx-adapter presets.Open question for Oded: is V1 willing to ship a Node runtime + adapter tree for Claude/Codex, or is “install Node” + loud error the acceptable compromise?
— Cursor agent (Architect), on @omesser's behalf.
omesser commentedon Sep 17, 2026
Deep pass: non-
npxACP agents we missed (Architect, 2026-09-17)Sources (measured today):
https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json(v1.0.0, 41 agents)launch()today:claude/codex/pi(npx),cursor-agent/hermes/opencode/grok(PATH)Important distinction
Registry
distribution.npxmeans “install via npx package,” not “must run under npx forever.” After a global/brewinstall, many agents are a PATH binary (gemini --acp,copilot --acp, …). For shipping without Node, what matters is whether a binary (or already-installed CLI) exists — not the registry’s preferred install flavor.ai-buddy already covers (zero-npx at attach)
cursor-agentcursor-agent acp(registry:cursor, binary)hermeshermes acp(not in curated registry; on Agents page)opencodeopencode acp(registry: binary)grokgrok agent stdio(registry lists@xai-official/grokas npx install; PATH form works when CLI installed — same pattern as Gemini)Custom escape hatch already accepts any ACP stdio command (README notes Copilot).
Missed: registry binary agents (no npx required to run once installed)
High-signal / mainstream candidates for named presets or Chat landing:
goosegoose acpkimikimi acpjuniejunie --acp=truecrow-clicrow-cli acpstakpakstakpak acpvtcodevtcode acppoolsidepool … acppool acpkilokilo acp@kilocode/clidevindevin acpharnharn serve acpamp-acp./amp-acpcortex-codecortex acp servecorust-agentcorust-agent-acpkimchikimchi --mode acpmistral-vibevibe-acpsigitsigitantigravity-acpagy_acp_server.parMissed: PATH-native in acpx / Agents page but not (or only as npx) in registry
These are “install the CLI, then no npx at attach” if the vendor ships a real binary/
brewformula:gemini --acp(docs; alsobrew install gemini-cli)copilot --acp --stdioopenclaw acpkiro-cli-chat acpiflow --experimental-acpqodercli --acpqwen --acptraecli acp servezeroclaw acpfx acpdroid exec --output-format acpdroid@…raxol acpNot npx, but still a package runner (
uvx/ Python)fast-agentuvx fast-agent-acp …/fast-agent-mcp acpminion-codeuvx minion-code@… acpSame “declare the runner” problem as npx, different toolchain.
Still npx-only in registry (no binary distribution)
Includes our three:
claude-acp,codex-acp,pi-acp, plus Cline, Auggie, Qwen/Qoder (as packaged), Gemini/Copilot/Grok as registry install flavor, Factory Droid, etc. Full list in the JSON.Corrected recommendation for “prefer first-party / zero-npx”
We did miss a large surface. Practical V1 tiering:
gemini(gemini --acp),goose,copilot(finish Name the remaining major Harnesses, one smoked turn at a time #457), maybekimi/junieif we care about those user bases.antigravity-acpbinary.Open question for Oded: which of Gemini / Goose / Copilot / Kimi / Junie deserve named
launch()rows + landing buttons vs stay custom?— Cursor agent (Architect), on @omesser's behalf.
omesser commentedon Sep 17, 2026
Correction: Gemini CLI is sunset — Google path is Antigravity
Per @omesser: do not treat
gemini --acpas a V1 “prefer / named preset” candidate. Gemini CLI is sunset; the product is Antigravity (agy). That matches #603 (docs scrub) and #604 (reach Antigravity).What did change since #604 was written: the official ACP Registry now lists
antigravity-acpwith binary distribution hosted ondl.google.com(agy_acp_server.par/.exe, v1.1.1) — not a third-party wrapper. That is a different animal from the community adapters #604 surveyed, and from probing bareagy(which still has no ACP mode per #603).So the corrected Google row for the zero-npx census is:
gemini --acp— sunset; ignore for new workagy— still not ACP (docs(harness): Replace the sunset Gemini CLI row with Antigravity, which has no ACP mode #603)antigravity-acpbinary (agy_acp_server…) — first-party Google ACP server sidecar; needs smoke viaprobe-harness.shand a feat(harness): Name Antigravity through Google's first-party ACP server #604 refreshHighest-value new named zero-npx presets from the deep pass, with Gemini removed: Goose, Copilot (#457), maybe Kimi / Junie, plus revisit Antigravity via official
antigravity-acpunder #604.— Cursor agent (Architect), on @omesser's behalf.
omesser commentedon Sep 23, 2026
Census complete (2026-09-23)
Research note landed in PR #932 (draft, ready for review). All Done-when checkboxes satisfied.
What shipped:
Recommendations:
Evidence sources:
harness.rslaunch table lines 101-134 (3 npx, 4 PATH, 1 custom).Open questions for Oded:
PR: #932
Follow-ups: #928, #929, #930
Related: #726 (closed by #831), #604 (antigravity update), #457 (copilot, closed)
Leaving this issue open for Oded to close after review (or update Done-when if recommendation is amended).
— Cursor agent, on @omesser's behalf.
omesser commentedon Sep 23, 2026
Shipped — spike complete
#932 merged to main (
b9d5618). Research note on main:docs/research/runtime-dependencies.md.Done-when (all met):
Implementation leftovers live on those follow-ups. Closing this spike as completed.
— Cursor agent (Coder), on @omesser's behalf.
omesser commentedon Sep 29, 2026
Follow-up research on
npxalternativesThis spike's deferred item (“npx alternatives / first-party ACP binaries — V2”) got a measured note in #1147 →
docs/research/harness-without-npx.mdonmain(2a36804).V1 call on that PR: keep declaring Node/
npx(ADR-0035); do not pin or bundle for V1. UX follow-ups: #1160, #1161, #1162. First-party ACP binaries remain the named reopen trigger.No change to this closed spike.
— Cursor agent (Coder), on @omesser's behalf.