Troubleshooting
Start with quiver doctor
Section titled “Start with quiver doctor”quiver doctorIt checks the Quiver home, the library, the assignments and the setup of each installed assistant, including the session-start hooks of Claude Code, Codex, Cursor, Antigravity and VS Code, and reports each check as ok, warn or error. The last line names the latest Quiver release.
quiver doctor --fixThis applies the safe fixes: it creates missing parts of the Quiver home, commits uncommitted changes in local/, and deletes folders left over from an interrupted source add or remove. After asking, it unassigns skills that are not in the library and deletes copies of served skills that Claude Code also loads by itself. Copies committed in git and copies in plugins are only reported.
The assistant does not use a skill
Section titled “The assistant does not use a skill”- Is the skill served in this folder? Run
quiver statusin the folder the assistant works in. If the skill is missing, assign it withquiver add. - Did the server start in the right folder? Open
~/.quiver/logs/mcp.log. Theserver startedline names the folder and the project. An assistant that starts the server outside the project serves only global skills; setQUIVER_PROJECTin its MCP entry. See Connect an assistant. - Was the skill assigned during the session? The skill list the session-start hook adds is built when the session starts. Start a new session, or ask the assistant to call
list_skills. - Does the description say when to use it? The assistant decides from the description alone. Name the situations and words a request would use. See Writing skills.
- Is it Claude Desktop? It has no hook and drops the server's instructions, so the model does not get the skill list up front. Ask for Quiver's skills in the prompt; see Connect an assistant.
- Did the assistant say Quiver could not load something? A skill or setting the hook could not read is named in a
<quiver-notice>block, and the assistant tells you. Runquiver doctor, and look at~/.quiver/logs/hook.log.
An always-on skill does not load
Section titled “An always-on skill does not load”- Check how the assistant gets it.
quiver statuslists, per assistant, how always-on skills reach it. It sayshookonly when the session-start hook is in place. If it says the hook is missing, runquiver install. - Start a new session. The hook runs when a session starts, so a change reaches the model from the next session.
- Check for too few hook commands. An assistant takes only so much text from one hook command, so Quiver splits the text over several commands.
quiver doctorwarns when an assistant has fewer commands than your skills take.quiver install, or any command that changes skills, sets the number; runquiver install <assistant>to set it now. - Check that the hook runs this binary. After you move the binary or switch Node versions,
quiver doctorreports a hook that runs anotherquiver. Runquiver installagain. - Is it Claude Desktop? It has no hook. Ask for Quiver's skills in the prompt.
A skill is loaded twice
Section titled “A skill is loaded twice”Claude Code also loads skills from ~/.claude/skills, the project's .claude/skills and enabled plugins. If the same skill is there and in Quiver, it may load twice. quiver status warns about each copy; quiver doctor --fix deletes the copies that are safe to delete.
The assistant cannot start quiver
Section titled “The assistant cannot start quiver”- Installed with npm and a Node version manager: the path of
quiverchanges with the Node version. Runquiver installagain after switching. - Moved the binary: run
quiver installagain; it replaces a registration that points to another binary. - Desktop apps do not see your shell's
PATH.quiver installwrites the absolute path of the binary for them. For a hand-written entry, use the path thatquiver mcp configprints.
quiver install refuses a config file
Section titled “quiver install refuses a config file”A Cursor, Claude Desktop, Antigravity or VS Code config that is not valid JSON is reported and never overwritten. VS Code's mcp.json may hold comments: Quiver reads them, and writes the file without them after saving <file>.quiver-backup. Fix the file, or restore it from <file>.quiver-backup, and run the command again. For Codex, Quiver runs codex mcp add; if that fails, codex mcp list shows whether Codex can read its config.toml.
Two folders are the same project
Section titled “Two folders are the same project”A copied project folder keeps the original's .quiver.json. quiver status warns about it. Run quiver projects split in the copy to give it its own ID.
quiver update stops on a source
Section titled “quiver update stops on a source”A source whose history was rewritten with a force-push is not updated. If you trust the new history, run:
quiver update <source> --resetStill stuck
Section titled “Still stuck”Run the failing command with -v for more details, and open an issue with the output of quiver --version and quiver doctor. Report security problems privately; see Security.