@kheif/quiver 1.2.0 → 1.4.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 +40 -21
- 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
|
|
|
@@ -88,6 +88,7 @@ Run `quiver help <command>` for the details and examples of each.
|
|
|
88
88
|
| `quiver new <name>` | Create a local skill and assign it to this project (`--global`: every folder, `--none`: nowhere). |
|
|
89
89
|
| `quiver edit <id>` | Open a local skill in your editor, then check and commit it. |
|
|
90
90
|
| `quiver delete <id>` | Delete a local skill from the library. An assigned skill needs `--force`. |
|
|
91
|
+
| `quiver fork <source/skill>` | Copy a source skill into your own skills to change it; `--as` names the copy. The copy takes the original's place wherever it is assigned, and `quiver update` no longer changes it. |
|
|
91
92
|
| `quiver import` | Move the skills in this project's `.claude/skills` into the library (`--deep`: every folder of the project). Originals committed in git are kept; `--keep` keeps all. |
|
|
92
93
|
| `quiver import <folder>` | Move every skill in a folder and its subfolders into the library. Files that are not valid skills are listed at the end. |
|
|
93
94
|
| `quiver import <skill>` | Move one skill: its `SKILL.md`, its folder or a markdown file with frontmatter. `--name` renames it. |
|
|
@@ -101,11 +102,13 @@ Run `quiver help <command>` for the details and examples of each.
|
|
|
101
102
|
| `quiver source add <repo>` | Clone a skill repository: `owner/repo` (GitHub), a git URL or a local path. |
|
|
102
103
|
| `quiver source list` | List sources with their skill count and commit. |
|
|
103
104
|
| `quiver source remove <name>` | Delete a source. Refuses while its skills are assigned, unless `--force`. |
|
|
104
|
-
| `quiver update [<name>...]` |
|
|
105
|
+
| `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
|
+
| `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. 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). |
|
|
105
108
|
| `quiver projects` | List projects (`--json`); `rename`, `forget` and `split` manage them. |
|
|
106
109
|
| `quiver doctor` | Check the library, the assignments, copies of served skills in Claude Code and its setup (`--fix` applies the safe fixes). |
|
|
107
|
-
| `quiver
|
|
108
|
-
| `quiver
|
|
110
|
+
| `quiver 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 uninstall [assistant...]` | Remove it from them, or only from the assistants named. |
|
|
109
112
|
| `quiver mcp config` | Print the MCP config entry for any other assistant. |
|
|
110
113
|
| `quiver mcp` | Run the MCP server. Assistants start this. |
|
|
111
114
|
| `quiver completion <shell>` | Print the completion script for `bash`, `zsh`, `fish` or `powershell`. |
|
|
@@ -120,17 +123,28 @@ quiver completion zsh > "${fpath[1]}/_quiver"
|
|
|
120
123
|
|
|
121
124
|
## MCP server
|
|
122
125
|
|
|
123
|
-
`quiver
|
|
126
|
+
`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:
|
|
124
127
|
|
|
125
|
-
| Assistant |
|
|
128
|
+
| Assistant | Name | What it changes |
|
|
126
129
|
|---|---|---|
|
|
127
130
|
| Claude Code | `claude-code` | Runs `claude mcp add --scope user quiver -- <path to quiver> mcp`. |
|
|
131
|
+
| Codex | `codex` | Runs `codex mcp add quiver -- <path to quiver> mcp`, which writes `~/.codex/config.toml` (or `$CODEX_HOME`). The Codex CLI and app share it. |
|
|
128
132
|
| Cursor | `cursor` | Adds `quiver` to `mcpServers` in `~/.cursor/mcp.json`. |
|
|
129
|
-
| 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).
|
|
133
|
+
| 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
|
+
| Antigravity | `antigravity` | Adds `quiver` to `mcpServers` in `~/.gemini/config/mcp_config.json`, which the Antigravity CLI (`agy`) reads. |
|
|
135
|
+
| 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"`. |
|
|
130
136
|
|
|
131
|
-
An assistant counts as installed when
|
|
137
|
+
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.
|
|
132
138
|
|
|
133
|
-
|
|
139
|
+
`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.
|
|
140
|
+
|
|
141
|
+
**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.
|
|
142
|
+
|
|
143
|
+
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.
|
|
144
|
+
|
|
145
|
+
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.
|
|
146
|
+
|
|
147
|
+
**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).
|
|
134
148
|
|
|
135
149
|
For any other assistant, `quiver mcp config` prints the entry:
|
|
136
150
|
|
|
@@ -140,9 +154,9 @@ For any other assistant, `quiver mcp config` prints the entry:
|
|
|
140
154
|
|
|
141
155
|
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/`.
|
|
142
156
|
|
|
143
|
-
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.
|
|
157
|
+
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.
|
|
144
158
|
|
|
145
|
-
**Instructions.**
|
|
159
|
+
**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.
|
|
146
160
|
|
|
147
161
|
**Tools:**
|
|
148
162
|
|
|
@@ -152,39 +166,44 @@ Claude Code starts the server in the project folder. Other assistants may start
|
|
|
152
166
|
| `get_skill` | `id` | The skill's instructions, its extra files and its folder. |
|
|
153
167
|
| `get_skill_file` | `id`, `path` | One extra file of a skill, such as `references/checklist.md`. Large and binary files return their path instead. |
|
|
154
168
|
| `create_skill` | `name`, `description`, `body`, `scope` (`project` or `global`), optional `files` | Creates a local skill, commits it and assigns it. In a folder that is not a project yet, `project` scope registers it. |
|
|
169
|
+
| `update_skill` | `id`, any of `description`, `body`, `files` (an empty content deletes the file) | Changes a local skill and commits it as `update <name> (via MCP)`. Other frontmatter fields are kept. Source skills are read-only. |
|
|
170
|
+
| `search_skills` | `query` | Searches the whole library, also skills not assigned here, and marks each match as assigned here (`global` or `project`) or not. The assistant may suggest an unassigned skill, but asks before using it. |
|
|
155
171
|
|
|
156
172
|
**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.
|
|
157
173
|
|
|
158
|
-
**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
|
|
174
|
+
**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.
|
|
159
175
|
|
|
160
176
|
## Always-on skills: limits
|
|
161
177
|
|
|
162
|
-
- Changes take effect in the next session, because the
|
|
178
|
+
- Changes take effect in the next session, because the hook runs when a session starts.
|
|
163
179
|
- Only the skill's text is delivered. Plugin hooks, such as a per-message reminder, are not run.
|
|
164
|
-
-
|
|
180
|
+
- 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.
|
|
165
181
|
|
|
166
182
|
## Security
|
|
167
183
|
|
|
168
184
|
Skills give instructions to your assistant, and a skill can include scripts the assistant may run. A skill from a source is code you run on your own machine.
|
|
169
185
|
|
|
170
186
|
- Add only sources you trust, and read their skills before you assign them.
|
|
171
|
-
- `quiver update`
|
|
172
|
-
- Source skills are read-only in Quiver. To change one,
|
|
173
|
-
- `
|
|
187
|
+
- `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.
|
|
188
|
+
- Source skills are read-only in Quiver. To change one, fork it into your own skills with `quiver fork`.
|
|
189
|
+
- `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.
|
|
190
|
+
- `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.
|
|
191
|
+
- `update_skill` changes only skills served in the session's project, and never an always-on skill: change those yourself with `quiver edit`.
|
|
192
|
+
- `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.
|
|
174
193
|
|
|
175
194
|
To report a vulnerability in Quiver itself, see [SECURITY.md](SECURITY.md).
|
|
176
195
|
|
|
177
196
|
## Uninstall
|
|
178
197
|
|
|
179
|
-
The last command deletes your own skills too. To keep them, first push `~/.quiver/local` somewhere: it is a git repository.
|
|
198
|
+
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.
|
|
180
199
|
|
|
181
200
|
```sh
|
|
182
|
-
quiver
|
|
201
|
+
quiver uninstall # remove the MCP server and the session-start hooks from every assistant
|
|
183
202
|
rm "$(command -v quiver)" # remove the binary; with npm: npm uninstall -g @kheif/quiver
|
|
184
203
|
rm -rf ~/.quiver # delete the library
|
|
185
204
|
```
|
|
186
205
|
|
|
187
|
-
On Windows, after `quiver
|
|
206
|
+
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.
|
|
188
207
|
|
|
189
208
|
Projects keep their `.quiver.json`; delete it there if you no longer need it.
|
|
190
209
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kheif/quiver",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.4.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.4.0",
|
|
30
|
+
"@kheif/quiver-darwin-x64": "1.4.0",
|
|
31
|
+
"@kheif/quiver-linux-arm64": "1.4.0",
|
|
32
|
+
"@kheif/quiver-linux-x64": "1.4.0",
|
|
33
|
+
"@kheif/quiver-win32-arm64": "1.4.0",
|
|
34
|
+
"@kheif/quiver-win32-x64": "1.4.0"
|
|
35
35
|
}
|
|
36
36
|
}
|