@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.
- package/README.md +42 -17
- 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
|
|
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
|
|
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
|
|
111
|
-
| `quiver
|
|
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
|
|
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
|
-
|
|
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
|
-
**
|
|
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.**
|
|
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
|
|
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
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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
|
+
"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.
|
|
30
|
-
"@kheif/quiver-darwin-x64": "1.
|
|
31
|
-
"@kheif/quiver-linux-arm64": "1.
|
|
32
|
-
"@kheif/quiver-linux-x64": "1.
|
|
33
|
-
"@kheif/quiver-win32-arm64": "1.
|
|
34
|
-
"@kheif/quiver-win32-x64": "1.
|
|
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
|
}
|