Scrivener Stats

Scrivener Stats

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.history is 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:

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_est
• stats-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-history and 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 from scrivener-inspect's outline or find).
• Counts come only from items that have body text; folders and empty documents legitimately contribute zero. Absent content.rtf is normal, not corruption.

Related skills

• scrivener-inspect — open and explore the project: outline, read, find (use it to get the UUID to pass to stats).
• 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.