From 878603a23886ae9aa3824da856b3bb626a59271a Mon Sep 17 00:00:00 2001 From: Lloyd Engebretsen Date: Thu, 30 Jul 2026 19:34:43 -0400 Subject: [PATCH 1/3] docs: strip git-install refs, canonicalize npm install paths Replace all @github: git-install references with npm-canonical paths: - opencode.json plugin spec: @stablekernel/opencode-bgrun@0.1.2 - Human CLI: npm i -g @stablekernel/opencode-bgrun (primary path) - Cache path: $(npm root -g)/@stablekernel/opencode-bgrun/bin/ (no quoting needed) - install.sh guidance text updated (no behavior changes) Affects: README.md, skill/run-bg/SKILL.md, install.sh --- README.md | 33 +++++++++++++++++++++------------ install.sh | 14 ++++++-------- skill/run-bg/SKILL.md | 11 ++++++----- 3 files changed, 33 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 913af6b..e546a4c 100644 --- a/README.md +++ b/README.md @@ -91,20 +91,20 @@ scripts called from the agent via a bash tool. ## Install details -### Recommended: git-install via `opencode.json` (coworkers / CI) +### Recommended: npm install via `opencode.json` (coworkers / CI) Add the following entry to the `plugins` array in your `opencode.json`: ```json { "plugins": [ - "opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1" + "@stablekernel/opencode-bgrun@0.1.2" ] } ``` OpenCode installs the package into -`~/.cache/opencode/packages//node_modules/opencode-bgrun/` and loads the plugin +`$(npm root -g)/@stablekernel/opencode-bgrun/` and loads the plugin automatically on startup. No PATH setup is needed for the **agent (tool) path** — the plugin resolves `bin/bgrun` by absolute path at runtime. @@ -131,18 +131,28 @@ is required for the tool registration and completion poller to become active. ### Optional: human shell CLI The **`bgrun` tool** (plugin-registered) is what AI agents call and it works automatically -from the git-install — no PATH setup required. It also delivers the session-wake feature. +from the npm install — no PATH setup required. It also delivers the session-wake feature. The human shell commands (`bgrun`, `bgstatus`, `bgtail`, `bgclean`) are **optional and notify-only** — they fire a desktop notification on completion but do **not** wake an agent -session. (Agent-wake is exclusively the plugin `bgrun` tool.) After a git-install via +session. (Agent-wake is exclusively the plugin `bgrun` tool.) After an npm install via `opencode.json` those scripts are **not on your PATH**; typing `bgrun` in a terminal will produce `command not found`. #### Recommended: `install.sh --cli-only` -Run `./install.sh --cli-only` to symlink just the four CLI scripts into `~/.local/bin` without -touching the plugin or skill (which the git-install already provides): +**Recommended:** install via npm global: + +```bash +npm i -g @stablekernel/opencode-bgrun +``` + +This puts `bgrun`, `bgstatus`, `bgtail`, and `bgclean` on your PATH automatically via npm's +bin map. + +Alternatively, if you have the repo cloned, run `./install.sh --cli-only` to symlink just +the four CLI scripts into `~/.local/bin` without touching the plugin or skill (which the npm +install already provides): ```bash # If you have the repo cloned: @@ -153,10 +163,10 @@ touching the plugin or skill (which the git-install already provides): ``` `--cli-only` also works **without a clone** when the plugin is already installed via the -`opencode.json` git-spec. It auto-discovers the scripts inside OpenCode's package cache at: +`opencode.json` npm spec. It auto-discovers the scripts inside OpenCode's package cache at: ``` -~/.cache/opencode/packages/opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1/node_modules/opencode-bgrun/bin +$(npm root -g)/@stablekernel/opencode-bgrun/bin/ ``` The version tag in the path is discovered dynamically, so it keeps working across version @@ -167,11 +177,10 @@ To remove: `./uninstall.sh --cli-only`. #### Manual alternative -If you prefer, symlink directly from the cache. The path contains `#`, `:`, and `@` so it -**must be quoted**: +If you prefer, symlink directly from the npm global cache: ```bash -PKG="$HOME/.cache/opencode/packages/opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1/node_modules/opencode-bgrun" +PKG="$(npm root -g)/@stablekernel/opencode-bgrun" mkdir -p "$HOME/.local/bin" for cmd in bgrun bgstatus bgtail bgclean; do ln -sf "$PKG/bin/$cmd" "$HOME/.local/bin/$cmd" diff --git a/install.sh b/install.sh index 590a8d5..fd0ff47 100755 --- a/install.sh +++ b/install.sh @@ -6,12 +6,12 @@ # • Symlinks bin/, plugin/, and skill/ into the user's config dirs. # # --cli-only: PATH-only install for users who already have the plugin installed -# via the git-install spec in opencode.json. +# via the npm plugin spec in opencode.json. # • Skips npm, plugin symlink, and skill symlink. # • Discovers CLI scripts from (a) this repo clone or (b) the OpenCode cache. # # Safe to re-run; replaces existing symlinks, never clobbers real files. -# Coworkers: use the git-install plugin spec in the README instead. +# Coworkers: use the npm plugin spec in the README instead. set -eu SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" @@ -34,7 +34,7 @@ Usage: install.sh [OPTIONS] Options: --cli-only Install only the 4 CLI scripts (bgrun bgstatus bgtail bgclean) onto PATH (~/.local/bin/). Skips npm install, plugin symlink, - and skill symlink. Useful for git-install users who already + and skill symlink. Useful for npm-install users who already have the plugin loaded via opencode.json and just want shell access to the bg* helpers. @@ -118,10 +118,8 @@ if [ "$CLI_ONLY" -eq 1 ]; then ok "Linking CLI from: $CLI_SRC (repo clone)" else # (b) Discover from OpenCode plugin cache - # The cache path contains @ : # and an embedded / in the package spec, - # so the package spec spans two path segments: - # opencode-bgrun@github:stablekernel / opencode-bgrun#v0.1.1 - # We glob over both segments to handle any version. + # The npm cache path is well-formed: @stablekernel/opencode-bgrun@/ + # We glob over the version segment to handle any installed version. CACHE_MATCH="" CACHE_COUNT=0 @@ -144,7 +142,7 @@ if [ "$CLI_ONLY" -eq 1 ]; then printf " To fix, do one of:\n" printf " 1. Run this script from a repo clone (git clone stablekernel/opencode-bgrun).\n" printf " 2. Add the plugin to opencode.json first:\n" - printf " \"plugins\": [\"opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1\"]\n" + printf " \"plugins\": [\"@stablekernel/opencode-bgrun@0.1.2\"]\n" printf " then let OpenCode fetch it, and re-run: install.sh --cli-only\n" exit 1 fi diff --git a/skill/run-bg/SKILL.md b/skill/run-bg/SKILL.md index 43e621c..eae65af 100644 --- a/skill/run-bg/SKILL.md +++ b/skill/run-bg/SKILL.md @@ -82,7 +82,7 @@ as a fallback when no `.session` sidecar is present. **The plugin is required on OpenCode.** Without it, the human desktop notification still fires, but there is no live agent wake. Install the plugin by adding -`opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1` to the `plugin` array in your +`@stablekernel/opencode-bgrun@0.1.2` to the `plugin` array in your `opencode.json` (recommended), or run `./install.sh` from a repo clone for local dev. Restart OpenCode either way. See Setup below. @@ -108,18 +108,19 @@ deliverables. Today `bgrun` handles them at the notification rung only. ## Setup (one-time) -**1. Recommended — plugin via git-install:** +**1. Recommended — plugin via npm:** Add the spec to the `plugin` array in your `opencode.json`: ```json -{ "plugin": ["opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1"] } +{ "plugin": ["@stablekernel/opencode-bgrun@0.1.2"] } ``` OpenCode fetches the package automatically on next start. Restart OpenCode to load the plugin. This gives you the agent-facing `bgrun` tool and the session-wake feature. It does **not** put the human shell CLIs (`bgrun`, `bgstatus`, `bgtail`, `bgclean`) on your PATH. **2. Human shell CLI (optional, notify-only):** -To also get the shell CLIs on your PATH, run `./install.sh --cli-only`. It works from a -clone, or auto-discovers the git-installed package in OpenCode's cache without a clone. +Recommended: `npm i -g @stablekernel/opencode-bgrun` — puts all four CLI scripts on your +PATH via npm's bin map. Alternatively, run `./install.sh --cli-only` from a clone, or +auto-discovers the npm-installed package in OpenCode's cache without a clone. `./install.sh --help` shows all modes. Remove with `./uninstall.sh --cli-only`. **3. Local dev (from a clone):** From e3c6b9239fcd024b38f793d5877d1b4d7c7aaa0c Mon Sep 17 00:00:00 2001 From: Lloyd Engebretsen Date: Fri, 31 Jul 2026 17:18:51 -0400 Subject: [PATCH 2/3] fix: correct npm cache paths in README and install.sh --cli-only glob --- README.md | 12 ++++++------ install.sh | 9 +++++---- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index e546a4c..0042590 100644 --- a/README.md +++ b/README.md @@ -104,9 +104,9 @@ Add the following entry to the `plugins` array in your `opencode.json`: ``` OpenCode installs the package into -`$(npm root -g)/@stablekernel/opencode-bgrun/` and loads the plugin -automatically on startup. No PATH setup is needed for the **agent (tool) path** — the plugin -resolves `bin/bgrun` by absolute path at runtime. +`~/.cache/opencode/packages/@stablekernel/opencode-bgrun@/node_modules/@stablekernel/opencode-bgrun/` +and loads the plugin automatically on startup. No PATH setup is needed for the **agent (tool) +path** — the plugin resolves `bin/bgrun` by absolute path at runtime. ### Local / dev install (repo clone) @@ -166,10 +166,10 @@ install already provides): `opencode.json` npm spec. It auto-discovers the scripts inside OpenCode's package cache at: ``` -$(npm root -g)/@stablekernel/opencode-bgrun/bin/ +~/.cache/opencode/packages/@stablekernel/opencode-bgrun@/node_modules/@stablekernel/opencode-bgrun/bin/ ``` -The version tag in the path is discovered dynamically, so it keeps working across version +The version segment in the path is discovered dynamically, so it keeps working across version bumps. To use this mode you need the `install.sh` script itself — grab it from the repo or copy it from the cache dir above. @@ -180,7 +180,7 @@ To remove: `./uninstall.sh --cli-only`. If you prefer, symlink directly from the npm global cache: ```bash -PKG="$(npm root -g)/@stablekernel/opencode-bgrun" +PKG="$HOME/.cache/opencode/packages/@stablekernel/opencode-bgrun@0.1.2/node_modules/@stablekernel/opencode-bgrun" mkdir -p "$HOME/.local/bin" for cmd in bgrun bgstatus bgtail bgclean; do ln -sf "$PKG/bin/$cmd" "$HOME/.local/bin/$cmd" diff --git a/install.sh b/install.sh index fd0ff47..3af7c58 100755 --- a/install.sh +++ b/install.sh @@ -46,8 +46,9 @@ Modes: --cli-only PATH-only install. Source priority: 1. /bin/ (if running from a clone) - 2. ~/.cache/opencode/packages/opencode-bgrun@.../bin/ - (auto-discovered from OpenCode's plugin cache) + 2. ~/.cache/opencode/packages/@stablekernel/opencode-bgrun@.../ + node_modules/@stablekernel/opencode-bgrun/bin/ + (auto-discovered from OpenCode's plugin cache) If neither source is found, installation fails with guidance. EOF } @@ -126,7 +127,7 @@ if [ "$CLI_ONLY" -eq 1 ]; then # Expand the glob manually; iterate over potential matches. # Using a for loop with a glob is safe — bash expands it before the loop. # We use a sub-glob for the two-segment package spec, then check each hit. - for candidate in "$HOME"/.cache/opencode/packages/opencode-bgrun@*/opencode-bgrun*/node_modules/opencode-bgrun/bin; do + for candidate in "$HOME"/.cache/opencode/packages/@stablekernel/opencode-bgrun@*/node_modules/@stablekernel/opencode-bgrun/bin; do # If the glob found no matches, bash leaves the literal pattern — # check that the candidate actually exists as a directory. if [ -d "$candidate" ]; then @@ -150,7 +151,7 @@ if [ "$CLI_ONLY" -eq 1 ]; then if [ "$CACHE_COUNT" -gt 1 ]; then warn "Multiple cached plugin versions found — using the last (lexically highest) match." warn "Matches found:" - for candidate in "$HOME"/.cache/opencode/packages/opencode-bgrun@*/opencode-bgrun*/node_modules/opencode-bgrun/bin; do + for candidate in "$HOME"/.cache/opencode/packages/@stablekernel/opencode-bgrun@*/node_modules/@stablekernel/opencode-bgrun/bin; do if [ -d "$candidate" ]; then warn " $candidate" fi From c3634e7ca0601abd402754ceb15a1adc7090c9ba Mon Sep 17 00:00:00 2001 From: Lloyd Engebretsen Date: Fri, 31 Jul 2026 17:30:08 -0400 Subject: [PATCH 3/3] docs: update AGENTS.md and uninstall.sh to reflect npm as canonical install --- AGENTS.md | 8 +------- uninstall.sh | 2 +- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3cc50d4..a9e23b4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,16 +53,10 @@ CHANGELOG.md # Keep-a-Changelog format, backfilled through v0.1.2 ## Distribution -**Current blessed install (git-install, pre-npm):** -```json -{ "plugin": ["opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.2"] } -``` - -**Future canonical install (npm, once published):** +**Canonical install (npm):** ```json { "plugin": ["@stablekernel/opencode-bgrun@0.1.2"] } ``` -Once npm is live, git-install references should be removed from docs. **Human CLI on PATH (optional, notify-only):** ```bash diff --git a/uninstall.sh b/uninstall.sh index 90a479b..8ed0a56 100755 --- a/uninstall.sh +++ b/uninstall.sh @@ -62,7 +62,7 @@ done # Usage: remove_link # Accepted roots: # 1. $SCRIPT_DIR (dev/clone install) -# 2. $HOME/.cache/opencode/packages/ containing "opencode-bgrun" (git-install) +# 2. $HOME/.cache/opencode/packages/ containing "@stablekernel/opencode-bgrun" (npm install) remove_link() { local dest="$1"