@kheif/quiver 1.3.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +42 -17
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -34,7 +34,7 @@ The same steps for Windows: it installs `quiver.exe` into `%LOCALAPPDATA%\Progra
34
34
  npm install -g @kheif/quiver
35
35
  ```
36
36
 
37
- npm installs the binary for your platform; no install script runs. If you switch Node versions with nvm, fnm or volta, run `quiver mcp install` again afterwards, because the path of `quiver` changes with the Node version.
37
+ npm installs the binary for your platform; no install script runs. If you switch Node versions with nvm, fnm or volta, run `quiver install` again afterwards, because the path of `quiver` changes with the Node version.
38
38
 
39
39
  **Go:**
40
40
 
@@ -58,7 +58,7 @@ cd ~/code/app
58
58
  quiver new release-notes
59
59
  ```
60
60
 
61
- In a terminal, `quiver init` asks before each step: registering the MCP server (`quiver mcp install`), importing the skills in `~/.claude/skills` for every folder, and importing those in the current project's `.claude/skills`. Any step can be skipped and run later. `quiver init --yes`, or a run outside a terminal, only creates `~/.quiver`; any other command creates it too.
61
+ In a terminal, `quiver init` asks before each step: registering the MCP server (`quiver install`), importing the skills in `~/.claude/skills` for every folder, and importing those in the current project's `.claude/skills`. Any step can be skipped and run later. `quiver init --yes`, or a run outside a terminal, only creates `~/.quiver`; any other command creates it too.
62
62
 
63
63
  `quiver new` opens the new `SKILL.md` in `$VISUAL` or `$EDITOR`. Write one sentence in `description` on when the assistant should use the skill, and the instructions below the frontmatter. Quiver commits the skill in `~/.quiver/local` and creates `~/code/app/.quiver.json`. Commit that file, so the project keeps its ID in every clone.
64
64
 
@@ -66,6 +66,19 @@ Then start Claude Code in `~/code/app` and ask for the task, such as "write the
66
66
 
67
67
  `quiver status` shows what the assistant gets in the current folder. `quiver` alone sums it up in three lines, with a next step, before the command list.
68
68
 
69
+ ## The interactive panel
70
+
71
+ In a terminal, `quiver` without arguments opens a panel for everything above, with no command to remember. `?` lists the keys of the current section.
72
+
73
+ | Section | What it does |
74
+ |---|---|
75
+ | **1 Skills** | Your skills in four views (available here, the project's, global, all), grouped by source. Assign a skill to the project and to every folder independently, each as *On demand* or *Always on*. `n` creates a skill, `i` imports, `e` edits, `f` forks a source skill, `d` deletes, `p` pins. `/` searches. |
76
+ | **2 Projects** | The registered projects. Choose one to manage it from anywhere, rename it, forget it, or split a copied folder. |
77
+ | **3 Sources** | The skill repositories. `a` adds one, `u` checks for updates and shows what would change (`d` shows the patches) before it applies them, `x` removes one. While the panel is open, Quiver checks the sources for updates in the background, one at a time and only when online, and shows a notice; it pulls nothing without a key press. `updateCheckInterval` in `config.json` (a duration such as `"12h"`, default 6 hours) sets how often. |
78
+ | **4 Health** | The checks of `quiver doctor` and how always-on skills reach each assistant. `i` sets up the MCP server and hooks, `f` applies the safe fixes. Without a Quiver home, the panel offers to set it up. |
79
+
80
+ Every change goes through the same code as the matching command. `quiver sync` and the `--json` outputs stay on the command line.
81
+
69
82
  ## Concepts
70
83
 
71
84
  - **Library.** `~/.quiver/local/` holds your own skills, in a git repository Quiver commits to. `~/.quiver/sources/` holds cloned skill repositories. Set `QUIVER_HOME` to use another folder.
@@ -99,16 +112,16 @@ Run `quiver help <command>` for the details and examples of each.
99
112
  | `quiver search <text>` | Search the IDs, names and descriptions of every library skill, also unassigned ones, and show whether each is served here (`--json`). |
100
113
  | `quiver status` | Show the project in this folder and the skills served here, with a warning for each copy Claude Code also loads (`--json`). |
101
114
  | `quiver where <id>` | Show where one skill is assigned (`--json`). |
102
- | `quiver source add <repo>` | Clone a skill repository: `owner/repo` (GitHub), a git URL or a local path. |
115
+ | `quiver source add <repo>` | Clone a skill repository: `owner/repo` (GitHub), a git URL or a local path. An `http://` or `git://` address is refused, because it is not encrypted; set `"allowInsecureSources": true` in `~/.quiver/config.json` to allow it, and Quiver still warns. |
103
116
  | `quiver source list` | List sources with their skill count and commit. |
104
117
  | `quiver source remove <name>` | Delete a source. Refuses while its skills are assigned, unless `--force`. |
105
118
  | `quiver update [<name>...]` | Download the latest skills of all or some sources and show what would change: the changed files of each assigned skill, with scripts marked "needs review". Asks before it applies changes to assigned skills (`--yes` does not ask, `--diff` shows the whole change). Pinned skills stay at their commit. |
106
119
  | `quiver pin <source/skill> [<commit>]` | Keep a source skill at its current commit, or the one given, so `quiver update` leaves it alone. `quiver unpin` goes back to the source's current version. |
107
- | `quiver sync init <git-remote>` | Keep the Quiver home in a git remote, so your other machines get the same skills, sources and assignments. Run it on each machine; then `quiver sync` commits, pulls and pushes, merges assignment changes from both machines and clones sources added elsewhere. |
120
+ | `quiver sync init <git-remote>` | Keep the Quiver home in a git remote, so your other machines get the same skills, sources and assignments. Run it on each machine; then `quiver sync` commits, pulls and pushes, merges assignment changes from both machines and clones sources added elsewhere. Before it pulls changes that make a skill always-on, change an always-on skill's files or add a source, it lists them and asks (`--yes` takes them). |
108
121
  | `quiver projects` | List projects (`--json`); `rename`, `forget` and `split` manage them. |
109
122
  | `quiver doctor` | Check the library, the assignments, copies of served skills in Claude Code and its setup (`--fix` applies the safe fixes). |
110
- | `quiver mcp install [assistant...]` | Register the MCP server with every supported assistant that is installed, or only with the assistants named. See [MCP server](#mcp-server). |
111
- | `quiver mcp uninstall [assistant...]` | Remove it from them, or only from the assistants named. |
123
+ | `quiver install [assistant...]` | Register the MCP server and add the session-start hook where the assistant has one, in every supported assistant that is installed, or only in the assistants named. See [MCP server](#mcp-server). |
124
+ | `quiver uninstall [assistant...]` | Remove it from them, or only from the assistants named. |
112
125
  | `quiver mcp config` | Print the MCP config entry for any other assistant. |
113
126
  | `quiver mcp` | Run the MCP server. Assistants start this. |
114
127
  | `quiver completion <shell>` | Print the completion script for `bash`, `zsh`, `fish` or `powershell`. |
@@ -123,7 +136,7 @@ quiver completion zsh > "${fpath[1]}/_quiver"
123
136
 
124
137
  ## MCP server
125
138
 
126
- `quiver mcp install` sets up every supported assistant that is installed. Name assistants to set up only those, such as `quiver mcp install codex cursor`. The supported assistants:
139
+ `quiver install` sets up every supported assistant that is installed. Name assistants to set up only those, such as `quiver install codex cursor`. The supported assistants:
127
140
 
128
141
  | Assistant | Name | What it changes |
129
142
  |---|---|---|
@@ -132,10 +145,19 @@ quiver completion zsh > "${fpath[1]}/_quiver"
132
145
  | Cursor | `cursor` | Adds `quiver` to `mcpServers` in `~/.cursor/mcp.json`. |
133
146
  | Claude Desktop | `claude-desktop` | Adds `quiver` to `mcpServers` in `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). |
134
147
  | Antigravity | `antigravity` | Adds `quiver` to `mcpServers` in `~/.gemini/config/mcp_config.json`, which the Antigravity CLI (`agy`) reads. |
148
+ | VS Code (Copilot) | `vscode` | Adds `quiver` to `servers` in `~/Library/Application Support/Code/User/mcp.json` (macOS; `%APPDATA%\Code\User\mcp.json` on Windows, `~/.config/Code/User/mcp.json` on Linux), with `"type": "stdio"`. |
149
+
150
+ An assistant counts as installed when its command (`claude`, `codex`) is on `PATH`, or when its config folder exists (`~/.gemini/antigravity-cli` for Antigravity, VS Code's user folder for VS Code; VS Code Insiders keeps its files under `Code - Insiders`). In the JSON files, every other key stays as it is, including an `env` of the `quiver` entry, and the old file is saved next to it as `<file>.quiver-backup`. A file that is not valid JSON is reported and never overwritten. When Codex already has a `quiver` entry, its `env` is kept too. Restart the assistant afterwards. `quiver doctor` checks the entry of each installed assistant. Every assistant but Claude Code gets the path of the binary itself, never the npm launcher, because desktop apps do not see your shell's `PATH` and so cannot find `node`. Cursor passes the skill list to the model and starts the server in the workspace folder, so project skills work there. The earlier names `quiver mcp install` and `quiver mcp uninstall` still work as hidden, deprecated aliases.
151
+
152
+ `quiver install` ends with one line per assistant saying how always-on skills reach it, and `quiver status` lists the same. For an assistant without a session-start hook it names the always-on skills, which do not load by themselves there.
153
+
154
+ **Claude Code, Codex, Cursor, Antigravity and VS Code** get a session-start hook that adds the always-on skills' text at the start of every session, so they always reach the model. Claude Code, Codex, Antigravity and VS Code also run it for each sub-agent; Cursor's sub-agent event cannot add text, so it has only the session-start hook. VS Code's hook is one file Quiver owns, `~/.copilot/hooks/quiver.json`, which both its harnesses read. Codex's hooks are trusted automatically through `codex app-server`; if that fails, `quiver install` prints the "Review hooks" step. `quiver doctor` reports a Claude Code, Codex, Antigravity or VS Code hook that is missing, runs another binary, or (Codex) needs review.
155
+
156
+ The hook passes the always-on skills in full, global ones first, and then the ID and description of every other skill served in the folder. An assistant takes only so much text from one hook command (Claude Code 10,000 characters, Antigravity about 48,900 bytes), so Quiver splits the text over as many hook commands as the assistant needs and nothing is left out. Each part says which one it is, and a skill is cut between parts only when it is longer than one. `quiver install`, and every command that changes skills, sets the number of commands to what your skills take (a project's own always-on skills count too); `quiver doctor` warns when an assistant has fewer commands than the text takes. The parts of one session start share one text: the first command builds it and the others read it, so a skill edited meanwhile cannot give them different texts.
135
157
 
136
- An assistant counts as installed when its command (`claude`, `codex`) is on `PATH`, or when its config folder exists (`~/.gemini/antigravity-cli` for Antigravity). In the JSON files, every other key stays as it is, including an `env` of the `quiver` entry, and the old file is saved next to it as `<file>.quiver-backup`. A file that is not valid JSON is reported and never overwritten. When Codex already has a `quiver` entry, its `env` is kept too. Restart the assistant afterwards. `quiver doctor` checks the entry of each installed assistant. Every assistant but Claude Code gets the path of the binary itself, never the npm launcher, because desktop apps do not see your shell's `PATH` and so cannot find `node`. Cursor passes the skill list to the model and starts the server in the workspace folder, so project skills work there.
158
+ A session never starts silently without its skills. A skill that cannot be read is left out and named, and so is anything else the hook could not do (an unreadable registry, a `.quiver.json` that is not a small file, a folder that has the project ID of another folder, as a copied repository does); the assistant is told in a `<quiver-notice>` block and tells you. Text that reaches the model is cleaned: hidden characters are dropped and a skill cannot write Quiver's own tags. `~/.quiver/logs/hook.log` records each run with a hash of the text it passed.
137
159
 
138
- **Codex, Claude Desktop and Antigravity** use Quiver's skills only when you ask for them in the prompt, such as "check the quiver skills for this"; `quiver mcp install` says so. Codex loads an MCP server's tools, and with them its instructions, only when the model searches for them. Antigravity puts the instructions in a file the model rarely reads. Claude Desktop drops them. Once asked, Codex and Antigravity also follow the always-on skills; Claude Desktop does not. Codex and Antigravity start the server in the project folder, so project skills work there. See [docs/spike-mcp-clients.md](docs/spike-mcp-clients.md).
160
+ **Claude Desktop** uses Quiver's skills only when you ask for them in the prompt, such as "check the quiver skills for this"; `quiver install` says so, because Claude Desktop drops the server's instructions. Antigravity starts the server in the project folder, so project skills work there. VS Code starts it in your home folder and sends the workspace as an MCP root, which Quiver reads after startup to serve that project's skills. See [docs/spike-mcp-clients.md](docs/spike-mcp-clients.md).
139
161
 
140
162
  For any other assistant, `quiver mcp config` prints the entry:
141
163
 
@@ -145,9 +167,9 @@ For any other assistant, `quiver mcp config` prints the entry:
145
167
 
146
168
  The server serves the project of the folder it is started in, or of `$QUIVER_PROJECT` when that is set. It logs to `~/.quiver/logs/`.
147
169
 
148
- Claude Code starts the server in the project folder. Other assistants may start it somewhere else, such as your home folder; there it serves only the global skills. Cursor starts it in the workspace folder. Claude Desktop never starts it in a project. Set `QUIVER_PROJECT` in that assistant's MCP config to serve a project's skills.
170
+ Claude Code starts the server in the project folder. Other assistants may start it somewhere else, such as your home folder; there it serves only the global skills, unless the assistant sends its workspace as an MCP root (VS Code), which Quiver reads to find the project. Cursor starts it in the workspace folder. Claude Desktop never starts it in a project. Set `QUIVER_PROJECT` in that assistant's MCP config to serve a project's skills.
149
171
 
150
- **Instructions.** When a session starts, the server tells the assistant which skills exist here: their IDs and descriptions, the always-on skills, and that new skills are saved with `create_skill`.
172
+ **Instructions.** The server's instructions stay short: how to use its tools (`get_skill`, `get_skill_file`, `list_skills`, `search_skills`), that new skills are saved with `create_skill`, and the names of the always-on skills, which an assistant without a session-start hook loads with `get_skill`. The skills themselves come from the hook above: the always-on skills in full and the others as ID and description.
151
173
 
152
174
  **Tools:**
153
175
 
@@ -162,13 +184,13 @@ Claude Code starts the server in the project folder. Other assistants may start
162
184
 
163
185
  **Prompts.** Every served skill is also an MCP prompt. In Claude Code it appears as `/quiver:<id>`; text after the command is passed to the skill as the task.
164
186
 
165
- **Live updates.** While a session runs, the server watches the library. Skills you add, remove or change show up in `list_skills` and the prompts right away. The skill list in the instructions is built once, so it changes from the next session on.
187
+ **Live updates.** While a session runs, the server watches the library. Skills you add, remove or change show up in `list_skills` and the prompts right away. The hook's text is built when a session starts, so it changes from the next session on.
166
188
 
167
189
  ## Always-on skills: limits
168
190
 
169
- - Changes take effect in the next session, because the instructions cannot change during a session.
191
+ - Changes take effect in the next session, because the hook runs when a session starts.
170
192
  - Only the skill's text is delivered. Plugin hooks, such as a per-message reminder, are not run.
171
- - Subagents are not reliable: in testing, one of two subagents followed the always-on skill.
193
+ - Sub-agents get the text from the sub-agent hook, in the assistants that have one (Claude Code, Codex, Antigravity, VS Code); Cursor has none.
172
194
 
173
195
  ## Security
174
196
 
@@ -177,21 +199,24 @@ Skills give instructions to your assistant, and a skill can include scripts the
177
199
  - Add only sources you trust, and read their skills before you assign them.
178
200
  - `quiver update` downloads new commits before it applies them, lists the changed files of every assigned skill, marks scripts and executable files "needs review", and asks before it applies the changes. Read them with `quiver update --diff`; answering no leaves the source as it was. To review changes to a skill before it reaches your sessions, pin it with `quiver pin` and move the pin when you have read them.
179
201
  - Source skills are read-only in Quiver. To change one, fork it into your own skills with `quiver fork`.
202
+ - `quiver sync` takes in what another machine pushed, so it lists changes that make a skill always-on, change an always-on skill or add a source, and asks first; use a private remote.
203
+ - `get_skill` and `search_skills` read the whole library, not only the skills assigned to the project; assign only what you want a project's sessions to see by name.
204
+ - `update_skill` changes only skills served in the session's project, and never an always-on skill: change those yourself with `quiver edit`.
180
205
  - `create_skill` and `update_skill` let the assistant write skills into your library. A global skill's description reaches the assistant in every folder, so review new global skills with `quiver list` and `quiver edit`. Every change is a commit in `~/.quiver/local` (in `~/.quiver` once you use `quiver sync`), so `git -C ~/.quiver/local log -p` shows it and `git revert` undoes it.
181
206
 
182
207
  To report a vulnerability in Quiver itself, see [SECURITY.md](SECURITY.md).
183
208
 
184
209
  ## Uninstall
185
210
 
186
- The last command deletes your own skills too. To keep them, first push `~/.quiver/local` somewhere: it is a git repository.
211
+ The last command deletes your own skills too. `quiver init` and `quiver import` moved the skills you had in `~/.claude/skills` and in projects' `.claude/skills` into `~/.quiver/local`, so that folder holds the only copy of them. To keep them, first push `~/.quiver/local` somewhere: it is a git repository.
187
212
 
188
213
  ```sh
189
- quiver mcp uninstall # remove the MCP server from every assistant
214
+ quiver uninstall # remove the MCP server and the session-start hooks from every assistant
190
215
  rm "$(command -v quiver)" # remove the binary; with npm: npm uninstall -g @kheif/quiver
191
216
  rm -rf ~/.quiver # delete the library
192
217
  ```
193
218
 
194
- On Windows, after `quiver mcp uninstall`, delete `%LOCALAPPDATA%\Programs\quiver` and `%USERPROFILE%\.quiver`, and remove the folder from your user `PATH` in the environment variables settings.
219
+ On Windows, after `quiver uninstall`, delete `%LOCALAPPDATA%\Programs\quiver` and `%USERPROFILE%\.quiver`, and remove the folder from your user `PATH` in the environment variables settings.
195
220
 
196
221
  Projects keep their `.quiver.json`; delete it there if you no longer need it.
197
222
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kheif/quiver",
3
- "version": "1.3.0",
3
+ "version": "1.5.0",
4
4
  "description": "Central skill manager for AI assistants, delivered as an MCP server.",
5
5
  "license": "Apache-2.0",
6
6
  "keywords": [
@@ -26,11 +26,11 @@
26
26
  "node": ">=18"
27
27
  },
28
28
  "optionalDependencies": {
29
- "@kheif/quiver-darwin-arm64": "1.3.0",
30
- "@kheif/quiver-darwin-x64": "1.3.0",
31
- "@kheif/quiver-linux-arm64": "1.3.0",
32
- "@kheif/quiver-linux-x64": "1.3.0",
33
- "@kheif/quiver-win32-arm64": "1.3.0",
34
- "@kheif/quiver-win32-x64": "1.3.0"
29
+ "@kheif/quiver-darwin-arm64": "1.5.0",
30
+ "@kheif/quiver-darwin-x64": "1.5.0",
31
+ "@kheif/quiver-linux-arm64": "1.5.0",
32
+ "@kheif/quiver-linux-x64": "1.5.0",
33
+ "@kheif/quiver-win32-arm64": "1.5.0",
34
+ "@kheif/quiver-win32-x64": "1.5.0"
35
35
  }
36
36
  }