hold your voice

hyv is now a part of ellora

hold your voice (hyv) checks writing locally. it compares a draft with your writing samples, flags generic writing patterns, and checks an edited candidate before you use it. you supply the writing and the edits; hyv supplies inspectable findings and verification.

it works through a command-line tool, an mcp server, and portable agent contracts. it needs node.js 20 or newer. it makes no model calls and needs no account or api key.

what it does

| check or workflow | result | | --- | --- | | voice dna | compares sentence structure, rhythm, vocabulary, punctuation, and other measurements with a local profile. | | ai editor | flags deterministic wording and structural patterns, with sentence locations and repair guidance. | | profiles | builds v2 or v3 profiles, assesses sample readiness, composes profiles, watches local sample files, and scores against held-out samples. | | fact and logic checks | compares claims with supplied source files and checks document structure, required facts, and claim polarity. | | hidden-text checks | inspects unicode controls, applies an explicit removal policy, and gates the exact final text. | | delivery checks | optionally checks placeholders, likely secrets, local links, and supplied citation ids offline. | | editing and rebuilding | prepares fingerprint-bound tasks, accepts a supplied response, preserves locked text or required claims, and verifies the candidate. | | review and approval | binds semantic judgments and signed approval capabilities to the exact candidate. | | local learning | records explicit instructions or verified repairs and applies profile revision and authority rules. | | evaluation | runs local backtests, synthetic comparisons, and evidence-bound benchmark workflows. |

voice fit, generic-pattern findings, factual evidence, and approval stay separate. a passing check does not prove authorship, truth, or publication quality.

install

npm install --global @holdyourvoice/hyv

for a one-off command, replace hyv with npx @holdyourvoice/hyv.

check and edit a draft

build a profile from at least two writing samples you have the right to use:

hyv profile profile.json samples/one.md samples/two.md
hyv analyze draft.md profile.json

analyze returns separate voice dna, ai editor, and hygiene reports. hygiene is informational here; use final-check to gate delivery.

create an editing brief, give it to your editor or a model you choose, then check the candidate:

hyv rewrite-prompt draft.md profile.json > rewrite-brief.md
hyv verify draft.md candidate.md profile.json
hyv final-check candidate.md

before verification, the editing brief asks for a word economy review: every word must earn its place. cut filler, repeated ideas, and needless setup when removing them loses no meaning, evidence, clarity, or voice. preserve necessary uncertainty, attribution, emphasis, and rhythm. this is an editor or model judgment, not an automatic score or a word-count target. edits must stay within the authorized scope.

rewrite and verification commands are strict by default: every active ai editor finding must be repaired. a v3 profile can deliberately disable a rule. verification also checks preservation, logic, required facts when supplied, and final-output hygiene. it does not record learning.

final-check writes accepted text to stdout. it removes a leading byte-order mark; unresolved hidden characters withhold output and return exit code 2. run it after the last edit or formatting change. stdin works too:

producer | hyv final-check -

commands

most commands return json. exit code 0 means completion, 2 means a content or policy gate failed, and 1 means invalid input or a command error. run a command without enough arguments for its usage, or read the full cli reference.

| command | purpose | | --- | --- | | profile <output> <sample...> | build a v2 profile; repeat --avoid=phrase for blocked phrases. | | profile v3 <output> --id=writer.channel --channel=email <sample...> | build a revisioned, digest-bound v3 profile. | | profile assess <sample...> | check sample readiness. | | profile compose --ratio 70:30 <profile...> | combine v3 measurements and conservative rule policies. | | profile watch ... | rebuild a local profile as its sample files change. | | team-profile validate\|compose ... | work with consent-bound team metadata. | | ingest ... | import owner-authorized gmail or telegram exports into redacted local samples. | | analyze <draft> <profile> | run the writing checks. | | score <draft> <profile-v3> <heldout...> | compare against a separate local writing range; abstain when evidence is inadequate. | | strict-check <draft> <profile-v3> <sample...> | return strict-ready, needs-human-review, or blocked using calibrated voice evidence. | | dispositions <draft> <profile> | normalize findings into block, review, and signal. | | patterns | print the active rule catalog. | | batch-analyze <draft...> | find repeated openings and endings. | | fact-lint <draft\|-> --source=id:path | check claims against supplied local sources. | | logic-lint <draft\|-> [brief.json] | check deterministic document logic. | | hygiene <draft> [--fix] | inspect hidden characters or write a conservative cleaned copy. | | inspect-hidden-text <draft> [policy.json] | inspect with an optional hidden-text policy. | | apply-hidden-text-policy <draft> <policy.json> <output> | apply explicitly permitted removals. | | final-check <path\|-> | gate the exact output text. | | delivery-check <path\|-> [policy.json] | run the separate optional delivery check. | | rewrite-prompt <draft> <profile> | prepare a constrained editing brief. | | prepare-rewrite ... / apply-rewrite ... | prepare and verify sentence replacements or range edits. | | prepare-judgment ... / reduce-judgment ... | collect and reduce pre-edit or post-candidate judgments. | | prepare-rebuild ... / rebuild-writer-request ... / apply-rebuild ... | run a whole-document rebuild with required claims and signed authorization. | | verify <original> <candidate> <profile> | verify an edited candidate. | | verify-spec ... | also enforce a CopySpec claim contract. | | lifecycle ... | prepare semantic review, submit verdicts, inspect state, and finalize approval or rejection. | | learning ... | inspect, add, ratify, supersede, migrate, or clear local learning. | | backtest ... / evaluate-local ... | evaluate supplied candidates locally without generating writing. | | agent list\|validate\|describe\|emit | inspect or emit portable agent contracts. | | mcp | start the local server over standard input/output. |

strict-check requires a v3 profile built from at least five samples, plus five non-duplicate validation samples with a consistent visible format and at least 1,500 words in total.

whole-document rebuilding requires an upstream REBUILD recommendation, a CopySpec, and a signed hyv.rebuild-authorization capability. it checks required claims instead of enforcing the ordinary lexical preservation threshold. semantic review and final approval remain separate steps. see the workflow and architecture and recomposition contract.

use with an agent

start the mcp server with hyv mcp. compatible hosts can call the same local checks through tools. the skills/hyv-* packages describe inputs, outputs, evidence, permissions, and stop conditions for agent workflows.

hyv agent list
hyv agent validate

setup guides: codex, claude desktop, claude code, and portable agents.

local data

hyv has no runtime network requests, telemetry, hosted analysis, or profile sync. samples, drafts, profiles, candidates, and source files stay local unless you choose to send them elsewhere.

learning lives under ~/.hyv/learning/ by default. verified-repair events store findings and hashes rather than draft text. explicit learning instructions store the instruction itself. approval trust is loaded separately from a permission-checked local context. private samples and approval keys do not belong in a public repository.

when you run hyv in a terminal, it prints one line on stderr with a link to a feedback form. the line is text. hyv sends nothing and opens nothing. it stays out of pipes, files, ci, and hyv mcp, so agent and script output does not change. set HYV_NO_FEEDBACK=1 to hide it.

version 4 and development

version 4 rebuilds the implementation boundaries while retaining the existing cli commands, mcp contracts, profile formats, deep-import paths, rules, and agent packages. existing profiles need no migration. verification artifacts include the package version: prepare fresh version-bound tasks and approvals after upgrading.

start with architecture to find the owner of a behavior. the compatibility check compares the rebuilt implementation with the frozen v3 source, including serialized outputs and errors.

npm ci
npm test
npm run check:release
npm run pack:claude

read contributing, rule authoring, the roadmap, and the wiki. existing runtime measurements describe their recorded fixtures and revisions; they are not a new version 4 performance claim. public synthetic scorecards do not measure human preference.

license

mit. third-party writing and data keep their own rights.