Hold Your Voice

Hold Your Voice is an MIT-licensed, local-first writing gate for people who want AI help without losing the parts of their writing that make it theirs.

It checks a draft through two separate programs:

• VoiceDNA compares the draft with 13 observable elements from your own local writing samples.
• AI Editor flags a small, versioned set of editorial patterns that can make writing generic, formulaic, or inflated.

Those programs keep separate findings, scores, and pass states. A strong result from one never cancels a failure in the other. The tool creates a tiered editing brief, then checks the candidate again before you accept it.

Everything runs from local files: accounts, API calls, MCP servers, telemetry, payment collection, and runtime network requests stay out of the core path.

Status: the public CLI is published as @holdyourvoice/hyv. It runs locally and makes no runtime network requests.

Why it exists

A draft can avoid obvious AI-shaped writing and still sound unlike its author. It can also match a writer’s short sentences while leaning on empty persuasion templates. Those are different problems. Treating them as one generic score hides the useful signal.

Hold Your Voice keeps the work visible:

Its scope is a local writing gate. Authorship detection, fact checking, plagiarism review, and hosted generation each need their own tools. Hold Your Voice gives a writer or chosen model a narrow editing brief, then asks the same two engines to inspect the result.

Start here

Requirements

• Node.js 20 or newer.
• npm.
• At least two local writing samples you have the right to use.

Install and verify

npx @holdyourvoice/hyv patterns

Run any command without a global install with npx @holdyourvoice/hyv. To use the short hyv command repeatedly:

npm install --global @holdyourvoice/hyv
hyv patterns

To contribute, clone this repository, run npm install, then run npm test and npm run check:release.

Build a local VoiceDNA profile

npx @holdyourvoice/hyv profile profile.json samples/one.md samples/two.md --avoid=overused-phrase

Use writing by one person, with a similar audience and format where possible. The command needs at least two samples. It creates a portable JSON profile and keeps the samples on your machine. Repeat --avoid=phrase for each local phrase that must block a candidate.

Inspect a draft

npx @holdyourvoice/hyv analyze draft.md profile.json

The result is JSON with independent reports:

{
  "voiceDna": { "score": 93, "passed": true, "findings": [] },
  "aiEditor": { "score": 88, "passed": true, "findings": [] },
  "passed": true
}

Read both reports. The outer passed field means each engine passed. Scores remain independent.

Create an editing brief

npx @holdyourvoice/hyv rewrite-prompt draft.md profile.json > rewrite-brief.md

Give the brief and draft to a human editor or any model you trust. This repository stays out of that provider call. Ask for replacement sentences keyed by sentence number, then save the output as a separate candidate file.

Verify the candidate

npx @holdyourvoice/hyv verify draft.md candidate.md profile.json

verify returns the original and candidate reports, identifies newly introduced findings, calculates a coarse preservation score, and exits with status 2 when the candidate fails the dual gate. It exits with 1 for a usage or runtime error. Treat status 2 as a release signal in scripts or CI.

The editing loop

flowchart LR
  S[Your local samples] --> P[Build profile]
  P --> D[VoiceDNA JSON]
  T[Draft] --> A[Analyze]
  D --> A
  A --> V[VoiceDNA report]
  A --> E[AI Editor report]
  V --> B[Tiered brief]
  E --> B
  B --> C[Human or chosen model]
  T --> G[Verify candidate]
  C --> G
  D --> G
  G --> R[Pass or inspect regressions]

The tool never applies changes to your draft. You decide which findings are valid, apply replacement sentences deliberately, and run the final check.

The five rewrite tiers

The prompt has an order. Lower tiers can refine a higher tier; they cannot override it.

1. Tier 0: preservation. Keep facts, names, numbers, claims, and every unflagged sentence exactly. Keep the response within the supplied sentences.
2. Tier 1: release blockers. Resolve profile avoid-list phrases and red findings.
3. Tier 2: VoiceDNA. Use the 13 profile elements as a writer-specific target.
4. Tier 3: AI Editor. Inspect yellow findings. Change a line only when the repair helps.
5. Tier 4: output. Return replacement sentences keyed by sentence number.

This order protects meaning before style. Read the complete prompt contract before changing it.

VoiceDNA: 13 observable elements

VoiceDNA is a local profile of writing mechanics drawn from the samples you choose. It makes no claim about personality. Its structural measurements support Unicode writing; the current point-of-view and transition lists are English-specific evidence.

An explicit profile avoid list creates red findings. The other evidence-only elements are calculated and shown. Future enforcement needs a written policy, counterexamples, and tests.

Read the full VoiceDNA reference and Wiki guide.

AI Editor: inspectable rules

AI Editor uses a local, deterministic ruleset. Each rule has a stable ID, severity, reason, and repair direction. Run this command to see the rules that actually execute in your checkout:

npx @holdyourvoice/hyv patterns

Red findings are release blockers. Yellow findings are a request to inspect a sentence in context. A match never proves who wrote the text, and a clean scan never proves the text is good.

The repository also includes a public 220-pattern editorial catalog. That catalog is broader than the executable ruleset on purpose. A catalog entry becomes executable only after the project has defined its counterexamples, reviewed public provenance, written tests, and decided the rule is narrow enough to help without creating noise.

Verification contract

Verification analyzes the original and candidate with the same profile and ruleset. It passes only when:

• VoiceDNA passes.
• AI Editor passes.
• The candidate introduces zero new red findings.
• The lexical preservation score is at least 70.

The preservation score is a guardrail based on retained original words longer than four characters. A human still needs to review facts, source links, intent, and reader value.

Commands

Every file argument can be - when the command accepts text input from standard input. Profile output is always written to the path you give it. Use npx @holdyourvoice/hyv <command> in place of hyv <command> when you have not installed the CLI globally.

Project map

pipeline.ts is the sole composition point. It combines pass states and preserves each engine’s separate score.

Privacy and data rights

The runtime uses files on your machine. Samples, drafts, profiles, candidates, feedback history, embeddings, and client data stay there.

Keep writing samples, edit histories, client text, embeddings, and datasets out of public commits unless you hold explicit rights and a provenance record. A profile is aggregated JSON and can still reveal vocabulary and preferences. Store private profiles outside public repositories.

See the privacy guide for maintainer and contributor boundaries.

Benchmarks and claims

The repository preserves historical product material in docs/BENCHMARKS.md, with related public articles about the Voice Memory Composer and Hold Your Voice vs GPT-5.6 writing.

Treat those as dated reference material. A reproducible benchmark needs rights-cleared data, frozen settings, a published rubric, separate dimensions, and visible limitations. The benchmark guide explains the standard.

Documentation

Contribute

npm test
npm run check:release

Read CONTRIBUTING.md before opening a pull request. Keep changes narrow. Add tests when code behavior changes. Separate current executable behavior, editorial guidance, historical research, and proposals. Keep private, client, secret, and unlicensed material out of issues, fixtures, tests, and documentation.

npm releases

@holdyourvoice/hyv is published automatically after a change to the package source reaches main. The workflow publishes only when the version in package.json is not already on npm, so bump that version in the same pull request as a release-worthy change. It runs the tests and release audit before publishing, then verifies that npm reports the package as MIT licensed.

Support

Hold Your Voice stays fully open source. Read the funding policy or sponsor maintenance on GitHub with a one-time or recurring sponsorship. Sponsorship funds maintenance while the feature set and local privacy contract remain the same for everyone.

License

MIT. You can use, modify, and distribute the code under its terms. Third-party writing and data retain their own rights.