Brand Voice

brand-voice

Brand writing enforcement for Claude Code — automatic, configurable, zero-friction.

Every time Claude writes or edits a Markdown file, brand-voice checks it against your brand guidelines and signals Claude to fix violations before the file saves. No manual review. No rule reminders in every prompt.

Claude reads the violation list, corrects the file, and retries the write — automatically.

---

Why brand-voice?

Your brand guidelines live in a doc somewhere. Claude doesn't read them unless you paste them into every prompt. Even then, the rules drift over time.

brand-voice makes the rules structural:

• Works for any company — configure your own vocabulary, voice, and visual identity
• Auto-corrects, doesn't just report — the PostToolUse hook blocks bad writes and triggers a retry
• Covers the full stack — hook for Claude Code, MCP server for on-demand checks, CLI for CI pipelines
• Smart about code — ignores fenced blocks, indented code, inline code spans, and table cells
• Escape hatches — .brand-voice-ignore for whole files, for individual lines
• Visual identity included — colors, fonts, logo URLs live in the same guidelines file

---

Install

npm install -g brand-voice

Or run without installing:

npx brand-voice@latest check

Requires Node.js 18+.

---

Quick Start

Option A — Guided setup in Claude Code (recommended)

Run the setup skill inside any Claude Code session:

/brand-voice-setup

The skill does everything:

1. Asks whether you have existing brand docs or want to answer four questions
2. Optionally researches your brand automatically via web
3. Writes brand-guidelines.md to your project
4. Injects a summary block into CLAUDE.md
5. Registers the PostToolUse hook in .claude/settings.json
6. Registers the MCP server in .mcp.json

After setup, every .md and .mdx file Claude touches is checked automatically.

Option B — Manual setup

# 1. Install

npm install -g brand-voice

2. Create brand-guidelines.md in your project root (see schema below)

3. Register the hook

brand-voice setup

---

How It Works

Three components work together:

What gets checked

Code blocks, inline code, indented blocks, and table rows are never checked — only prose.

Never checked: physical line length or line breaks. The CLAUDE.md injection always includes a formatting rule telling Claude to write continuous paragraphs and let the renderer word-wrap, but the analyzer itself has no line-width rule and never will — sentence length is measured in words, not characters or lines, so hard-wrapped and unwrapped prose score identically.

PostToolUse hook exit codes

Exit 1 is never used (it aborts the session rather than triggering a retry).

---

brand-guidelines.md

One Markdown file holds your entire brand configuration. Keep it under 600 words so it fits cleanly in context.

# Brand Guidelines

Persona

Who you are and who you write for.

Tone & Voice

• Direct, honest, clear
• Person: second ← "first" | "second" | "third"
• Voice: active ← "active" | "passive"
• Sentences: max 25 words
• Contractions: yes ← "yes" | "no"
• Exclamation marks: no

Vocabulary

Always use: Acme, Acme Platform, APIs Avoid: leverage, utilize, synergy, seamless Forbidden: [competitor names, unverified claims]

On-Tone Examples

Connect your data in minutes — Acme handles the routing.

Off-Tone Examples

Leverage our cutting-edge platform to seamlessly integrate.

Visual Identity

• Primary color: #006EFA
• Secondary color: #0050C3
• Accent color: #FF9DFF
• Background color: #FFFFFF
• Text color: #282828
• Logo (light): https://cdn.example.com/logo-light.svg
• Logo (dark): https://cdn.example.com/logo-dark.svg
• Heading font: Inter
• Body font: Source Sans Pro

Formatting Rules

• Heading style: sentence case
• Oxford comma: yes
• Readability target: 8th grade

Quick Reference

Repeat your top 5 rules here. This section appears last — where LLM attention is highest — to reinforce critical rules against context-window attention drop-off.

See example/brand-guidelines.md for a complete working example.

Section aliases

## On-Brand Examples and ## Off-Brand Examples are accepted as aliases for ## On-Tone Examples / ## Off-Tone Examples. All other section names are case-insensitive exact matches.

Search path

The hook and CLI search for brand-guidelines.md in this order:

1. Current working directory
2. ~/.claude/brand-guidelines.md (user scope — enforces rules across all your projects)
3. Parent directories up to the git root

---

Suppressing Violations

Skip files or directories — .brand-voice-ignore

Create a .brand-voice-ignore file in your project root. Uses gitignore-style patterns:

# Auto-generated content

dist/ CHANGELOG.md

Agent prompt files — intentional brand vocabulary exceptions

data/prompts/**

Vendor docs

vendor/

Skip a single line — inline comment

<!-- brand-voice-disable-line -->

Add this comment anywhere on a line to suppress all violations on that line. Useful for one-off exceptions where the violation is intentional.

---

MCP Server

analyze_readability

Check a file or inline text for violations and readability scores.

Inputs:

Returns: { filePath, passed, violations[], readabilityScores, visualIdentity }

apply_suggestions

Apply safe word-level substitutions for forbidden/avoid terms. Does not fix sentence length, passive voice, or grade — those need human judgment.

Inputs:

Returns: diff + change list (dry run) or confirmation + change list (live)

Tip: Run dryRun: true first to preview, then apply.

---

CI Integration

brand-voice works independently of Claude Code — add it to any pipeline.

Check all `.md` files:

npx brand-voice@latest check

Check only files changed in the current branch:

npx brand-voice@latest check --changed-only

GitHub Actions inline annotations (PR diff comments):

npx brand-voice@latest check --reporter github-pr-review

Ratchet enforcement — block regressions without requiring a clean slate:

# Run once, commit the file

npx brand-voice@latest baseline --save

In CI: fail only if violations increase above baseline

npx brand-voice@latest check --baseline .brand-voice-baseline.json

Example GitHub Actions workflow:

name: Brand Voice

on: pull_request: paths: ['.md', '.mdx']

jobs: prose: runs-on: ubuntu-latest steps:

• uses: actions/checkout@v4 with: { fetch-depth: 0 }
• run: npx brand-voice@latest check --changed-only --reporter github-pr-review

Exit 0 = clean or within baseline. Exit 1 = errors found or baseline exceeded.

---

CLI Reference

brand-voice <command> [options]

Commands: check [file] Check a file or all .md files in cwd setup Print instructions to run /brand-voice-setup in Claude Code import Normalize a brand-guidelines.md into cwd baseline --save Save current violation count as ratchet baseline vale-sync Check that the Vale binary is available

Check options: --changed-only Only check files changed in git (requires git) --baseline Compare against a baseline JSON file (ratchet check) --reporter github-pr-review Emit GitHub Actions annotation format

---

Programmatic API

import { parseGuidelines, analyzeText, loadGuidelines } from 'brand-voice';

const guidelines = loadGuidelines(process.cwd()); if (guidelines) { const result = analyzeText(markdownString, 'doc.md', guidelines); console.log(result.violations); // Violation[] console.log(result.readabilityScores); // ReadabilityScores console.log(result.passed); // false if any error-severity violations }

See src/types.ts for full type definitions.

---

Distribution Patterns

---

Requirements

• Node.js 18+
• `brand-guidelines.md` — created by /brand-voice-setup or written manually
• Vale — optional; only required for vale-sync

---

Contributing

Bug reports, feature requests, and pull requests are welcome. See CONTRIBUTING.md for setup instructions, key invariants to preserve, and code style guidance.

---

License

MIT — see LICENSE.