Install Vellum — Claude Code plugin quickstart

Requirements

Claude CodeThe host application. The plugin is installed through its marketplace.
GitHooks run under the bash bundled with Git for Windows, so Git is required on Windows as well as for cloning.
Python ≥ 3.8On PATH as python3, python, or the Windows py -3 launcher. Standard library only; nothing to pip install.
Pandoc (optional)DOCX and PDF export only. The markdown bundle and EPUB build without it.

Install from GitHub

Inside Claude Code:

/plugin marketplace add FiredMosquito831/my-writing-companion
/plugin install vellum@my-writing-companion

Prefer the terminal? The same two steps:

claude plugin marketplace add FiredMosquito831/my-writing-companion
claude plugin install vellum@my-writing-companion

Verify with /plugin — vellum should be listed and enabled. After the next session start, the /vellum: commands are live.

From a local clone

git clone https://github.com/FiredMosquito831/my-writing-companion.git
claude plugin marketplace add ./my-writing-companion
claude plugin install vellum@my-writing-companion

Use the absolute path to the clone instead of ./my-writing-companion if Claude Code is launched from another directory.

Your first session

Work in your novel folder — a new empty directory or an existing manuscript. Both are supported.

Set up the project
Run /vellum:init, or tell Claude “Set up my novel project.” The project-setup skill interviews you — genre, POV, progress, and three to five samples of your own prose — seeds manuscript/, kb/, state/, work/, and export/, copies the engine in, builds kb/styles/voice.md plus a measured baseline from your samples, and runs the initial state rebuild.
Read the dashboard
/vellum:status prints the state card, gate statuses, and the resume pointer. From now on every session begins with the card on screen.
Write a chapter
/vellum:write-chapter next — or a specific chapter number. The outliner proposes beats with word quotas and verbatim anchor lines; you approve the outline, and that approval is what disarms gate 1. Say “pivotal” when the chapter is load-bearing. Only you set that flag.
Draft, critique, accept
The writer receives a fixed context pack. The post-write net runs silently. Critics report; the muse synthesizes; you accept. Pivotal chapters also need the blind reader's verdict before acceptance.
Capture and close
Acceptance fires word counts, ledger checks, and a state rebuild; the knowledge lead extracts what happened into the ledgers. Before a chapter goes final, one demolition pass is offered. You may decline.
Later
/vellum:cold-read for a cover-to-cover fresh-eyes pass with a rolling reader ledger. /vellum:retune to recalibrate voice from a raw sample. /vellum:export for the readiness gate and the build.

What setup actually gives you

A project that already contains the full engine, the templates, a measured voice baseline, and a state card derived from whatever prose is on disk. There is no separate “generate the project” step and no hand-written configuration required.

The eight commands

Command	What it does
/vellum:init	Set up a novel project. Set up a creative-writing project for this plugin — run the project-setup skill (interview, kb layout, CLAUDE.md, initial state rebuild).
/vellum:write-chapter	Write a chapter. Run the chapter loop — outline, author approval, draft, critique, acceptance, capture.
/vellum:status	State card & gate status. Print the state card, gate statuses, and open findings summary.
/vellum:cold-read	Cold read. Set up work/cold-reads/<YYYY-MM> from templates/cold-read and run cold-read batches.
/vellum:retune	Retune the voice. Run the voice retune protocol from a raw author sample.
/vellum:export	Export the manuscript. Evaluate readiness, then build the export bundle.
/vellum:dismiss	Dismiss a finding. Record an author dismissal of a finding as an exemption (requires the reason in the author own words).
/vellum:series	Operate the series layer. Operate the library/series layer — link books, capture series canon, run retcon checks, plan and apply retcons.

The full generated reference →

The engine, when you want it directly

The engine runs from your project root. Everything the slash commands do mechanically is available here — useful for scripts, for checking what a gate believes, and for repairing state without spending model tokens.

python scripts/vellum --version          # engine version
python scripts/vellum state check        # gate preconditions
python scripts/vellum state rebuild      # rebuild the derived state card
python scripts/vellum readiness          # export-readiness evaluation
python scripts/vellum pack chapter-12    # deterministic writer context pack

Exit codes are stable: 0 clean, 1 findings, 2 schema or usage error. Subcommands cover state, ledger continuity, bible validation, word counts, knowledge queries, style statistics, context packing, dismissals, voice debt, revision plans, readiness, and export.

The series layer also exposes python scripts/library.py with its own subcommand surface — see the series layer.

Windows notes

Hooks run under Git Bash; no WSL is needed.
Interpreter resolution tries python3, then python, then py -3, each probed for version ≥ 3.8.
Gate 1's core predicate is pure bash, so the outline gate still works if Python is missing. Engine preconditions then fail open with a one-line advisory.
Paths with drive letters, spaces, CRLF line endings, and UTF-8 BOMs are covered by the Windows CI matrix.
Run the test suite from any bash: python -m pytest tests/ -q.

When a gate blocks you

A gate reports the artifact it wanted and the action that produces it. It does not lock the manuscript. The three common cases:

OutlineApprove the outline for that chapter. The frontmatter must read approved: true; the muse cannot set it for you.
Blind readA pivotal chapter needs a real @blind-reader run written to work/critique-reports/blind-chapter-NN.md with a verdict other than LOST.
ReadinessExport needs work/critique-reports/readiness-report.md with verdict: PASS. A failing report is also a prioritized fix list.

If state and prose disagree, Vellum surfaces the conflict rather than rewriting either. The full rescue manual lives in TUTORIAL.md §17.