You help the writer measure a Scrivener 3 project: total and per-item word/character counts, reading-time and page estimates, day-by-day writing history, and which words they overuse. Every command here is read-only — none of them mutate the project.
When to use
- "What's my word count?" / "How long is my manuscript?"
- "How long would this take to read?" / "How many (paperback) pages is this?"
- "What words do I overuse?" / "Show me my most common words."
- "Show my writing history." / "How many words did I write each day?"
- "Am I on track / hitting my target?" (report from history; deadline math is planned)
Commands
All commands take --project "<path.scriv>" and emit JSON by default
(--format text for a human-readable view). These are read-only — no backup,
snapshot, or --dry-run flags apply.
stats [<id>] — counts and estimates
With no id, reports the whole Draft. Pass a document or folder UUID/title to scope to that subtree.
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py stats --project "<path.scriv>"
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py stats <uuid> --project "<path.scriv>"
Returns words, characters, reading_time_minutes, paperback_pages_est,
documents_with_text, and scope (draft or item).
stats-history — per-day draft/other words
Reads Files/writing.history (Scrivener's own session log) and reports per-day
draft vs. other word counts plus totals.
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py stats-history --project "<path.scriv>"
Each day reports draft_words (manuscript), other_words (everything else), and
the session_target. Totals roll up draft_words, other_words, and
days_written.
writing.historyis read-only. Scrivener owns this file and rewrites it as the writer works. This skill only reads it — never regenerate or edit it. If the file is absent (e.g. a brand-new project), the result is simply empty.
stats-frequency [--top N] — word frequency
Lists the most-used words across the Draft (default top 50).
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py stats-frequency --project "<path.scriv>"
python3 ${CLAUDE_PLUGIN_ROOT}/tools/scrivener/cli.py stats-frequency --top 25 --project "<path.scriv>"
Returns unique_words and a top list of [word, count] pairs. Use this to spot
crutch words, repeated names, or overused adverbs.
Understanding the estimates
The estimates are deliberately simple, transparent rules of thumb — not Scrivener's exact figures. Tell the writer how each number is derived so they can judge it:
| Metric | How it's computed |
|---|---|
reading_time_minutes |
words ÷ 250 — about 250 words per minute silent reading |
paperback_pages_est |
words ÷ 350 — about 350 words per typeset page |
words / characters |
counted from each document's content.rtf after RTF→text conversion |
documents_with_text |
how many items actually contributed body text |
Reading speed and page density vary by reader, trim size, and font, so present these
as ballpark figures. Full detail (which items count, how subtrees roll up,
writing.history attributes) lives in references/metrics.md.
Toolkit support
✅ Available now:
stats [<id>]— words, characters, reading_time_minutes, paperback_pages_eststats-history— per-day draft/other word counts (read-only)stats-frequency [--top N]— word frequency across the Draft
🔜 Planned (not yet in the CLI):
- Per-document/folder targets and deadline math (words remaining, words/day
to hit a date). For now, read progress from
stats-historyand compute the gap by hand against the writer's stated goal. - CSV export of stats and writing-history. For now, hand the JSON output to the writer or another tool.
When asked for a planned feature, describe the workflow, say it isn't in the CLI yet, and offer the closest available command.
Safety
- These commands are read-only and never modify the project, so they are safe to run even while drafting. Still, results are most accurate once cloud sync (Dropbox/iCloud) has finished — a mid-sync project may have partial content.
- Binder titles are not unique — when scoping
stats <id>by title and the title is ambiguous, prefer the item's UUID (get it fromscrivener-inspect'soutlineorfind). - Counts come only from items that have body text; folders and empty documents
legitimately contribute zero. Absent
content.rtfis normal, not corruption.
Related skills
- scrivener-inspect — open and explore the project:
outline,read,find(use it to get the UUID to pass tostats). - scrivener-compile — assemble the Draft into Markdown/text; useful once length and frequency look right.
- scrivener-search — find and (planned) replace specific words flagged by
stats-frequency.