Brand Voice

brand-voice

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

[npm version] [npm downloads] [CI] [License: MIT] [Node.js 18+]

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.

[brand-voice demo]

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, <!-- brand-voice-disable-line --> 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. Installnpm install -g brand-voice
# 2. Create brand-guidelines.md in your project root (see schema below)
# 3. Register the hookbrand-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
## PersonaWho 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 ReferenceRepeat your top 5 rules here. This section appears last —where LLM attention is highest — to reinforce critical rulesagainst 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 contentdist/CHANGELOG.md
# Agent prompt files — intentional brand vocabulary exceptionsdata/prompts/**
# Vendor docsvendor/

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 filenpx brand-voice@latest baseline --save
# In CI: fail only if violations increase above baselinenpx brand-voice@latest check --baseline .brand-voice-baseline.json

Example GitHub Actions workflow:

name: Brand Voiceon:  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 <file>         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 <file>     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.