Skip to content

spike(ship): Census of runtime deps beyond the binary — self-contain or present cleanly #735

Closed

Description

@omesser

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

  1. 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 on PATH, 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”.
  2. Challenge each row — for every dep: keep / replace / vendor / document-only. Prefer self-contained when the cost is sane.
  3. 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.
  4. 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

Decisions (Oded, 2026-09-23) — locked on #932

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

— Cursor agent (Architect), on @omesser's behalf.

Activity

  1. added
    needs-triageMaintainer needs to evaluate this issue
    researchDefining or executing a research into an aspect: tech, direction, decision
    on Sep 15, 2026
  2. added this to the V1 milestone on Sep 15, 2026
  3. omesser commented on Sep 17, 2026

    @omesser
    OwnerAuthor

    Spike note: npx vs acpx (Architect, 2026-09-17)

    Feeds this census (#735). Motivating bug remains #726 (npx missing → silent Codex fail).

    What ai-buddy needs today

    From src-tauri/src/harness.rs launch():

    Preset argv Needs npx/Node?
    claude npx -y @agentclientprotocol/claude-agent-acp@latest yes
    codex npx -y @agentclientprotocol/codex-acp@latest yes
    pi npx -y pi-acp@latest yes
    hermes hermes acp no (CLI on PATH)
    opencode opencode acp no
    grok grok agent stdio no
    cursor-agent cursor-agent acp no
    custom split whitespace depends

    So npx is 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 acpx is

    • Repo / npm: openclaw/acpx · acpx on npm (v0.17.x). Node ≥22.13. MIT (per package).
    • Role: headless ACP client CLI (sessions, prompts, flows). Same protocol side as ai-buddy already occupies as Completer client.
    • Launch table: still resolves Claude/Codex/Pi to npx -y @agentclientprotocol/… / npx pi-acp (docs/agents.md). Native agents (cursor-agent, grok, …) do not need npx — same split we already have.
    • Rust cousin: motosan-dev/acp-cli (“Rust port of ACPX”) and boltz-one/acpx (embeddable Rust client) — still spawn those same npm adapters via npx.

    Conclusion: vendoring / sidecar-shipping acpx does not remove the Node/npx dependency for Claude/Codex/Pi. It would add a second ACP client (and usually still need Node to run acpx itself) next to our Rust client.

    Options that actually address npx

    Ranked for V1 honesty:

    1. Prefer / default first-party ACP harnesses (hermes, opencode, grok, cursor-agent) where the user has them — already zero-npx. Product/UX, not shipping Node.
    2. Declare loudly when 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.
    3. Sidecar a pinned adapter tree (optional, heavier): ship node + offline node_modules for the three packages (or node path/to/cli.js instead of npx -y). Removes network/npx cold start; still ships Node (~50–100MB+). Update cadence and licenses become ours.
    4. Do not vendor acpx as 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).
    5. Long shot: first-party claude acp / official binary adapters if/when upstream ships them — then drop Zed npm adapters for those rows.

    Recommendation for this census

    • Call on acpx: not a self-contain path for V1. Document as “looked at; wrong layer.”
    • Call on npx/Node: for Claude/Codex/Pi rows → declare (install Node + ensure npx on PATH) until/unless we deliberately take option 3.
    • Follow-ups to file (if not already): (a) bug(chat): Codex landing connect shows no error, chat header stuck on "codex - not running" #726 loud failure; (b) optional spike “bundle Node + pinned 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.

  4. omesser commented on Sep 17, 2026

    @omesser
    OwnerAuthor

    Deep pass: non-npx ACP agents we missed (Architect, 2026-09-17)

    Sources (measured today):

    • Official ACP Registry https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json (v1.0.0, 41 agents)
    • ACP Agents page
    • acpx built-in registry
    • ai-buddy launch() today: claude/codex/pi (npx), cursor-agent/hermes/opencode/grok (PATH)

    Important distinction

    Registry distribution.npx means “install via npx package,” not “must run under npx forever.” After a global/brew install, 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)

    Preset Command
    cursor-agent cursor-agent acp (registry: cursor, binary)
    hermes hermes acp (not in curated registry; on Agents page)
    opencode opencode acp (registry: binary)
    grok grok agent stdio (registry lists @xai-official/grok as 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:

    id Typical command Notes
    goose goose acp Block / open-source; strong “local agent” candidate
    kimi kimi acp Moonshot
    junie junie --acp=true JetBrains
    crow-cli crow-cli acp
    stakpak stakpak acp
    vtcode vtcode acp
    poolside pool … acp acpx: pool acp
    kilo kilo acp also offers npx @kilocode/cli
    devin devin acp
    harn harn serve acp
    amp-acp ./amp-acp
    cortex-code cortex acp serve
    corust-agent corust-agent-acp
    kimchi kimchi --mode acp
    mistral-vibe vibe-acp
    sigit sigit also npx
    antigravity-acp agy_acp_server.par Updates #604: registry now ships a binary ACP adapter for Google Antigravity — premise “agy has no ACP” may be stale

    Missed: 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/brew formula:

    Agent Command (acpx / docs) Registry
    Gemini CLI gemini --acp (docs; also brew install gemini-cli) registry entry is npx-only — big miss for named preset
    GitHub Copilot copilot --acp --stdio registry npx; README already “anything else”; #457 closed without named row
    OpenClaw openclaw acp Agents page; not in curated 41
    Kiro kiro-cli-chat acp acpx only
    iFlow iflow --experimental-acp acpx
    Qoder qodercli --acp registry npx package; acpx uses native CLI name
    Qwen Code qwen --acp registry npx; acpx native
    Trae traecli acp serve acpx
    ZeroClaw zeroclaw acp acpx
    fx fx acp acpx
    Factory Droid droid exec --output-format acp registry npx droid@…
    Raxol raxol acp Agents page only
    Docker cagent, OpenHands, Cline, … various often adapter/npx — check before naming

    Not npx, but still a package runner (uvx / Python)

    id Command Dep
    fast-agent uvx fast-agent-acp … / fast-agent-mcp acp uv, not Node
    minion-code uvx minion-code@… acp uv

    Same “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:

    1. Already named: cursor / hermes / opencode / grok — keep preferring these.
    2. Highest-value new named zero-npx (or PATH) presets to consider: gemini (gemini --acp), goose, copilot (finish Name the remaining major Harnesses, one smoked turn at a time #457), maybe kimi / junie if we care about those user bases.
    3. Revisit feat(harness): Name Antigravity through Google's first-party ACP server #604 against registry antigravity-acp binary.
    4. Don’t treat registry npx as “requires npx at runtime” for Gemini/Copilot/Grok/OpenCode — prefer PATH commands when the CLI is installed (ai-buddy already does this for grok/opencode).
    5. Custom argv remains the escape hatch for the long tail (kiro, iflow, stakpak, …) until smoked.

    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.

  5. omesser commented on Sep 17, 2026

    @omesser
    OwnerAuthor

    Correction: Gemini CLI is sunset — Google path is Antigravity

    Per @omesser: do not treat gemini --acp as 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-acp with binary distribution hosted on dl.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 bare agy (which still has no ACP mode per #603).

    So the corrected Google row for the zero-npx census is:

    Highest-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-acp under #604.

    — Cursor agent (Architect), on @omesser's behalf.

  6. moved this from Todo to In Progress in Fidgeton Sep 23, 2026
  7. omesser commented on Sep 23, 2026

    @omesser
    OwnerAuthor

    Census complete (2026-09-23)

    Research note landed in PR #932 (draft, ready for review). All Done-when checkboxes satisfied.

    What shipped:

    Recommendations:

    1. Accept "install Node" + loud error (fix(chat): Surface a missing Harness launcher on the landing #831) as V1 path for Claude/Codex/Pi. Do not bundle Node unless spike(ship): Bundle Node runtime + pinned ACP adapters for self-contained Claude/Codex/Pi #928 spike shows it is acceptable. Declare external dep.
    2. Declare Harness CLIs per preset. Present install steps in Settings/landing when selected CLI missing. Named presets stay: hermes, opencode, grok, cursor-agent. High-value additions: goose (feat(harness): Named preset for Goose (zero-npx, open-source local agent) #930), antigravity-acp (update feat(harness): Name Antigravity through Google's first-party ACP server #604 — registry now has official binary v1.1.1).
    3. Platform deps (WebView, GStreamer, FUSE) already documented. No change. Linux WebView declared in .deb deps + README. GStreamer optional (silent skip). FUSE for AppImage documented.
    4. Do not vendor acpx (wrong layer; still needs npx per architect 2026-09-17).
    5. Do not recommend Gemini CLI (sunset; Google path is Antigravity per architect correction).
    6. Prefer first-party ACP (zero-npx) in UX (feat(settings): Distinguish first-party ACP harnesses from npx-adapter presets in UI #929 Settings copy).

    Evidence sources:

    Open questions for Oded:

    1. Node bundling decision (V1 ship Node+adapters, or accept "install Node")?
    2. Named preset prioritization (goose / antigravity / junie / kimi)?
    3. Failure UX details (toast vs inline, retry without restart)?

    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.

  8. omesser commented on Sep 23, 2026

    @omesser
    OwnerAuthor
  9. moved this from In Progress to Done in Fidgeton Sep 23, 2026
  10. omesser commented on Sep 29, 2026

    @omesser
    OwnerAuthor

    Follow-up research on npx alternatives

    This spike's deferred item (“npx alternatives / first-party ACP binaries — V2”) got a measured note in #1147 → docs/research/harness-without-npx.md on main (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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    harnessneeds-triageMaintainer needs to evaluate this issueresearchDefining or executing a research into an aspect: tech, direction, decision

    Projects

    • Status
      Done

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions