|
1 | 1 | # Plugin Library |
2 | 2 |
|
3 | | -A local explorer for your agent plugins. Three panes: the plugins on this machine and in the marketplace → a plugin's skills, agents and rules → the full `SKILL.md` rendered in a reading pane, straight from disk. "Send to a bot" picks a target from the live [`gbot`](https://github.com/ScriptedAlchemy/grok-bot-cli) roster and asks before anything is sent. |
| 3 | +## Install |
4 | 4 |
|
5 | | -Ships as a Cursor / Grok Bot plugin: `/plugin-library` starts the server and opens it. |
| 5 | +Requires Node 22.19+ and npm. Generated Agent Bundle artifacts are committed in `artifact/` on `main`; no project dependency installation or local build is needed. |
6 | 6 |
|
7 | | -## Tour |
| 7 | +Install the bot picker CLI from npm before installing the plugin: |
8 | 8 |
|
9 | | -Installed plugins, sorted by how much they ship. Search covers plugin names, descriptions and skill ids. |
10 | | - |
11 | | - |
12 | | - |
13 | | -pstack's 47 skills, grouped the way the Catalog suggests (Workflows, Bot+style, Principles, Language), with agents and rules below. |
14 | | - |
15 | | - |
16 | | - |
17 | | -Click a skill and the full `SKILL.md` opens in the reading pane. Front matter becomes chips, sibling reference files become tabs, and relative links between them switch tabs instead of leaving the page. `#/p/9717366/s/why` is a shareable deep link. |
18 | | - |
19 | | - |
20 | | - |
21 | | - |
22 | | - |
23 | | -"Send to a bot" pulls the live roster from `gbot` (bots and groups) and ends in one sentence you confirm. Nothing is sent until you click Send. |
24 | | - |
25 | | - |
26 | | - |
27 | | - |
28 | | - |
29 | | -Every installed plugin gets the same treatment, not only pstack. |
30 | | - |
31 | | - |
32 | | - |
33 | | -Marketplace listings show catalog copy and can be sent to a bot too. |
34 | | - |
35 | | - |
36 | | - |
37 | | -## Run from a checkout |
38 | | - |
39 | | -Node 22.19+. The explorer reads `~/.cursor/plugins/cache` and `~/.cursor/plugins/local`; the bot picker needs `gbot` on `PATH` (without it the explorer still works and the picker says the roster is unavailable). |
40 | | - |
41 | | -```bash |
42 | | -git clone https://github.com/ScriptedAlchemy/plugin-library.git |
43 | | -cd plugin-library |
44 | | -npm start # http://127.0.0.1:8787/ |
45 | | -``` |
46 | | - |
47 | | -Or let the launcher manage the process: |
48 | | - |
49 | | -```bash |
50 | | -node bin/plugin-library.mjs open [query] [--json] [--browser] # start if needed, print or open a deep link |
51 | | -node bin/plugin-library.mjs status --json |
52 | | -node bin/plugin-library.mjs stop |
| 9 | +```sh |
| 10 | +npm install --global grok-bot-cli |
53 | 11 | ``` |
54 | 12 |
|
55 | | -`open pstack` resolves to `#/p/9717366`; `open why` to the skill inside it. `open` is idempotent: it reuses a running server or starts one detached (pid in `logs/server.pid`, output in `logs/server.out`). |
56 | | - |
57 | | -Default port **8787** (`PORT`). Binds `127.0.0.1` because it shells out to `gbot` and serves cache files without auth; set `HOST=0.0.0.0` only on a network you trust. `CURSOR_PLUGIN_CACHE`, `CURSOR_PLUGIN_LOCAL` and `GBOT_BIN` override the two plugin directories and the CLI. |
| 13 | +### Cursor: install from GitHub |
58 | 14 |
|
59 | | -## Install as a plugin |
| 15 | +Dashboard → Plugins → Team Marketplaces → Add Marketplace: |
60 | 16 |
|
61 | | -The `agent-bundle-artifact` branch is the generated, validated plugin root (built by CI on every push to `main`). |
| 17 | +```text |
| 18 | +https://github.com/ScriptedAlchemy/plugin-library |
| 19 | +``` |
62 | 20 |
|
63 | | -**Cursor, from GitHub.** Dashboard → Plugins → Team Marketplaces → Add Marketplace, import `https://github.com/ScriptedAlchemy/plugin-library`, pick the `agent-bundle-artifact` branch, then install **Plugin Library**. (Team Marketplaces need a Teams or Enterprise plan.) |
| 21 | +Use the default `main` branch and install **Plugin Library**. Team Marketplaces require a Teams or Enterprise plan. |
64 | 22 |
|
65 | | -**Cursor, without a team marketplace.** |
| 23 | +### Cursor: install from a clone |
66 | 24 |
|
67 | 25 | ```sh |
68 | | -git clone --branch agent-bundle-artifact --depth 1 https://github.com/ScriptedAlchemy/plugin-library.git |
69 | | -cd plugin-library && node ./install.mjs |
| 26 | +git clone --depth 1 https://github.com/ScriptedAlchemy/plugin-library.git |
| 27 | +cd plugin-library |
| 28 | +node artifact/install.mjs |
70 | 29 | ``` |
71 | 30 |
|
72 | | -Reload Cursor (`Developer: Reload Window`). `npx --no-install agent-bundle doctor --from . --host cursor` verifies the install. |
73 | | - |
74 | | -**Grok Bot.** The same generated root is an Agent Plugins 1.0.0 package: `plugin.json` plus `skills/`. Hand it to the host's plugin flow; the `plugin-library` skill teaches the bot to answer skill questions from the read-only API of an already-running explorer. The `/plugin-library` slash command is Cursor-only. |
75 | | - |
76 | | -**From a source checkout**, for a local proof: |
| 31 | +Reload Cursor with **Developer: Reload Window**, then run `/plugin-library` in an agent session to open the explorer. |
77 | 32 |
|
78 | | -```bash |
79 | | -npm ci && npm run build |
80 | | -node artifact/install.mjs |
81 | | -``` |
| 33 | +The npm package provides `gbot` on `PATH`. Sign in to Grok Bot before using the bot picker. |
82 | 34 |
|
83 | | -In the installed plugin the launcher lives at `scripts/plugin-library.mjs` (the command file uses `${CURSOR_PLUGIN_ROOT}/scripts/plugin-library.mjs`); in this repo it is `bin/plugin-library.mjs`. |
| 35 | +### Other Agent Plugins hosts |
84 | 36 |
|
85 | | -Then in an agent session: |
| 37 | +Use the committed `artifact/` directory with your host's plugin installer. It contains `plugin.json`, skills, bundled executables, and assets. The `/plugin-library` slash command is Cursor-only. |
86 | 38 |
|
87 | | -- `/plugin-library` opens the explorer (embedded browser when the session has one, OS browser otherwise). |
88 | | -- `/plugin-library pstack` or `/plugin-library why` deep-links to that plugin or skill. |
| 39 | +## Screenshots |
89 | 40 |
|
90 | | -Agents never call `POST /api/send`; the bundled command and skill both say so. Sending to a bot is a click you make. |
| 41 | + |
91 | 42 |
|
92 | | -## API |
| 43 | + |
93 | 44 |
|
94 | | -| Route | Returns | |
95 | | -|-------|---------| |
96 | | -| `GET /api/library` | `{ installed, marketplace, groups }`. *Installed* means present in this machine's plugin cache or local plugin directory; catalog rows supply copy, category and ids. Plugins with no catalog row get `local:<name>`-style ids. | |
97 | | -| `GET /api/local/<marketplace>/<slug>/doc/<path>` | `{ meta, markdown }` for any `.md`/`.mdc` inside that plugin | |
98 | | -| `GET /api/local/<marketplace>/<slug>/file/<path>` | any other file inside that plugin (logos, scripts). Symlinks and `..` that leave the plugin root are 404 | |
99 | | -| `GET /api/bots` | live bots + groups from `gbot bots list` / `gbot groups list` (20s cache; `?refresh=1` bypasses) | |
100 | | -| `POST /api/send` | `{ plugin_id, bot_ref, skill_id? }`, same-origin JSON only. Verifies the plugin, skill and target, then runs `gbot send <target> <message>`. Used by the UI after you confirm. | |
| 45 | + |
101 | 46 |
|
102 | | -## Data |
| 47 | + |
103 | 48 |
|
104 | | -`data/unified-catalog.json` is a snapshot of the Cursor marketplace (names, descriptions, categories, ids); `data/pstack.json` is the Catalog's suggested grouping for pstack's skills. Both are read server-side only and copied into the built plugin. Everything else (skills, agents, rules, logos) is read live from disk. When a plugin is cached twice (numeric id and slug), the copy Cursor marked `<hash>.installed` wins, then the highest version. |
| 49 | + |
105 | 50 |
|
106 | | -## Develop |
| 51 | + |
107 | 52 |
|
108 | | -```bash |
109 | | -npm ci |
110 | | -npm run check # agent-bundle validate, tsc, build, node --test, artifact validate, packed-install smoke |
111 | | -``` |
| 53 | + |
112 | 54 |
|
113 | | -Screenshots in `screens/` are 1600×1000 @2x from a headless-Chrome tour with a stub `gbot` roster. |
| 55 | + |
![renovate[bot]](https://avatars.githubusercontent.com/in/2740?v=4&size=40){kind=avatar}
0 commit comments