From 2d3f172221dc56aa5c80ce89b000c7e2b316d205 Mon Sep 17 00:00:00 2001 From: fujibee Date: Wed, 10 Jun 2026 13:07:53 -0700 Subject: [PATCH 1/3] docs(readme): document npm and Claude Code plugin install paths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds two install paths the README didn't cover after the PH-launch rework: - **npm / npx** — published since #89 via npm Trusted Publisher (OIDC) with SLSA provenance. `npx agmsg` is the lowest-friction path for Node-having users. - **Claude Code plugin marketplace** — `/plugin marketplace add fujibee/agmsg` + `/plugin install agmsg@fujibee-agmsg` + `/reload-plugins` + `/agmsg`. Verified end-to-end against a fresh Debian-based Claude Code container today: the in-CC slash command flow runs the SKILL.md Step 0 bootstrap (added in #85) and lands on the same `~/.agents/skills/agmsg/` runtime as the direct-script install. Also surfaces the `bash + sqlite3` prerequisite at the top of Quick Start. The dogfood revealed that minimal Linux images (Debian slim, etc.) don't include sqlite3 by default; the bootstrap installer surfaces a clear error, but it's worth flagging up front. macOS users are unaffected. The Install section is restructured into subsections (npm, plugin marketplace, direct script) so each path stands on its own. A note in the direct-script subsection clarifies that `--cmd` / `--agent-type` flags are direct-script only — the other paths always install as `agmsg` with auto-detected agent type. --- README.md | 39 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3279f565..ff0329a6 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,8 @@ In real use it looks like this — Claude Code asking Codex for a code review an ## Quick Start +**Requires:** `bash` and `sqlite3`. macOS ships both. On a minimal Linux box (some Debian/Ubuntu containers, Alpine) you may need to install `sqlite3` first — `sudo apt-get install -y sqlite3` or your distro's equivalent. + ```bash # 1. Install (one-liner) bash <(curl -fsSL https://raw.githubusercontent.com/fujibee/agmsg/main/setup.sh) @@ -49,6 +51,8 @@ git clone https://github.com/fujibee/agmsg.git && cd agmsg && ./install.sh That's it. The slash command prompts you for a team name and an agent name on first use, then asks you to pick a [delivery mode](#delivery-modes) (default on Claude Code: `monitor` — real-time push; Codex defaults to `turn` because it has no Monitor tool). After that, you talk to your agent naturally — see [First run](#first-run) below. +Prefer a different install method? See [Install](#install) below for `npm` / `npx` and the Claude Code plugin marketplace paths. + ## How it works agmsg is a thin transport. Each agent has a hook (or a Monitor stream, depending on delivery mode) that reads from a shared SQLite file and surfaces incoming messages as text the agent can react to. Sending is a `send.sh` call that appends a row. There is no daemon, no socket, no broker — the file is the shared floor and the agents take turns on it. @@ -57,6 +61,33 @@ The store is WAL-mode SQLite, so multiple readers and a single writer coexist wi ## Install +agmsg ends up at `~/.agents/skills/agmsg/` no matter which install path you take. Pick whichever fits your setup. + +### npm / npx + +```bash +npx agmsg # one-shot, no global install +# or +npm i -g agmsg && agmsg install +``` + +The npm package is a thin bootstrapper that downloads and runs the canonical `setup.sh`. Published from this repo via [npm Trusted Publisher (OIDC)](https://docs.npmjs.com/trusted-publishers) with [SLSA provenance](https://slsa.dev/) — the attestation is visible at . + +### Claude Code plugin marketplace + +Inside Claude Code: + +``` +/plugin marketplace add fujibee/agmsg +/plugin install agmsg@fujibee-agmsg +/reload-plugins +/agmsg +``` + +The plugin install path drops the skill into `~/.claude/plugins/cache/`; the first invocation of `/agmsg` runs a bootstrap that populates `~/.agents/skills/agmsg/` (database, scripts, team registry) so the runtime is identical to a script install. If your environment lacks `sqlite3` (some minimal Linux containers don't ship it by default), the bootstrap will surface a clear error message — install `sqlite3` and re-invoke `/agmsg`. + +### Direct script + ```bash ./install.sh # Interactive (asks command name, default: agmsg) ./install.sh --cmd m # Non-interactive with custom command name @@ -65,10 +96,12 @@ The store is WAL-mode SQLite, so multiple readers and a single writer coexist wi The **command name** determines: - Skill folder: `~/.agents/skills//` -- Claude Code: `/` -- Codex/Gemini/Antigravity: `$` +- Claude Code / Copilot CLI: `/` +- Codex / Gemini CLI / Antigravity: `$` + +`--cmd` and `--agent-type` are only available via the direct-script path; the `npm` and plugin paths always install as `agmsg` and auto-detect the host agent type. -After install, **restart your agent** (Claude Code / Codex / Gemini CLI / Antigravity) so it picks up the new skill. +After install, **restart your agent** (Claude Code / Codex / Gemini CLI / Copilot CLI / Antigravity) so it picks up the new skill. ### Native Windows / PowerShell shortcut From cebae9e2ae05532948a0fd7ff327d4db1dd8521f Mon Sep 17 00:00:00 2001 From: fujibee Date: Mon, 15 Jun 2026 09:22:33 -0700 Subject: [PATCH 2/3] docs(readme): note which install path tracks main vs tagged releases git clone / setup.sh install from main (always current); the npm package and Claude Code plugin are cut from tagged releases and can lag. Point readers at `/agmsg version` to see exactly what they're running (#117 provenance). --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index ff0329a6..d76bbe1d 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,8 @@ The store is WAL-mode SQLite, so multiple readers and a single writer coexist wi agmsg ends up at `~/.agents/skills/agmsg/` no matter which install path you take. Pick whichever fits your setup. +**Which path gets the latest?** The `git clone` and `setup.sh` (curl) paths install straight from `main`, so they're always current. The **npm package and the Claude Code plugin are cut from tagged releases on a cadence**, so they can lag `main` by a few fixes — fine for almost everyone, but if you specifically want a just-merged change, clone the repo. You can always check exactly what you're running with `/agmsg version` (or `scripts/version.sh`): a tagged release reads like `v1.0.3`, while a checkout ahead of the last release reads like `v1.0.3-6-g1a2b3c4` (6 commits past `v1.0.3`). + ### npm / npx ```bash From be951e9b36b969e1917e51de450ad96d16025bdd Mon Sep 17 00:00:00 2001 From: fujibee Date: Mon, 15 Jun 2026 09:28:46 -0700 Subject: [PATCH 3/3] docs(readme): add clone step to Direct script; credit new contributors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Direct script section now shows the `git clone` + `cd` it assumed, and notes it's the path that tracks latest main. - Community: credit @lucianlamp (native Windows PowerShell helpers, #103) and @tatsuya6502 (sandboxed Bash tool support, #106) — merged but uncredited. --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d76bbe1d..9bc293e0 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,11 @@ The plugin install path drops the skill into `~/.claude/plugins/cache/`; the fir ### Direct script +Clone the repo first, then run the installer — this is also the path that always tracks the latest `main`: + ```bash +git clone https://github.com/fujibee/agmsg.git +cd agmsg ./install.sh # Interactive (asks command name, default: agmsg) ./install.sh --cmd m # Non-interactive with custom command name ./install.sh --agent-type gemini # Install a Gemini-oriented SKILL.md @@ -399,7 +403,7 @@ bats tests/ # requires bats-core: brew install bats-core - **Product Hunt**: #5 Product of the Day, [2026-06-09 launch](https://www.producthunt.com/products/agmsg) — 219 upvotes, 39 comments - **Derivative projects**: `agmsg-shogi`, `agmsg-go`, `agmsg-mcp` (community-built) -- **External contributors**: [@MiuraKatsu](https://github.com/MiuraKatsu) (Gemini support + whoami auto-detect), [@roundrop](https://github.com/roundrop) (Copilot CLI support), [@TOMONOSUKEJP](https://github.com/TOMONOSUKEJP) (native Windows / Git Bash), [@kenshin-yamada](https://github.com/kenshin-yamada) (watcher scoping fix), [@utenadev](https://github.com/utenadev) (OpenCode contribution) +- **External contributors**: [@MiuraKatsu](https://github.com/MiuraKatsu) (Gemini support + whoami auto-detect), [@roundrop](https://github.com/roundrop) (Copilot CLI support), [@TOMONOSUKEJP](https://github.com/TOMONOSUKEJP) (native Windows / Git Bash), [@kenshin-yamada](https://github.com/kenshin-yamada) (watcher scoping fix), [@utenadev](https://github.com/utenadev) (OpenCode contribution), [@lucianlamp](https://github.com/lucianlamp) (native Windows PowerShell helpers), [@tatsuya6502](https://github.com/tatsuya6502) (sandboxed Bash tool support) ## Contributing