voice (pi package)

A pi package that helps you build a corpus of your own writing, distill it into a style guide, and draft new text in your voice. Port of the my-voice Claude Code plugin, same directories, same workflow.

The premise: in-context grounding (rules + style guide + a few register-matched samples) outperforms generic LLM output for personal voice imitation, and beats most fine-tuning approaches at the corpus sizes individuals actually have. This package is the workflow.

Install

pi install npm:@guygrigsby/pi-voice

Or from a local checkout:

pi install /path/to/pi-extensions/voice -l

The package registers its skills as /skill:* commands. Check with pi list and /skill:voice-init.

Quick start

/skill:voice-init

That creates ~/.claude/voice/ (override with $VOICE_HOME) with starter templates and a corpus directory tree. Then:

1. Edit ~/.claude/voice/rules.md with your hard writing rules. The starter file lists the most common AI-tells (em dashes, leading "I"/"I'm", redundancy). Add your own. The more specific these are, the better drafts will land.
2. Populate the corpus. Pick the sources you have:
   • /skill:voice-pull-emails — sent mail via a Gmail MCP server
   • /skill:voice-pull-blog <url> — your blog or any URL with prose
   • bash ~/.claude/voice/scripts/pull_pr_descriptions.sh <github_username> — your GitHub PR descriptions
   • bash ~/.claude/voice/scripts/pull_review_comments.sh <github_username> — your PR review and conversation comments
3. Distill. /skill:voice-distill reads the corpus and (re)writes voice.md.
4. Draft. /skill:voice <register> <topic> produces text in your voice.

Skills

| Skill | What it does | | ---------------------------- | ----------------------------------------------------------------- | | /skill:voice | Draft text in your voice. Pass a register and a topic. | | /skill:voice-init | Create the corpus directory tree and copy templates. | | /skill:voice-distill | Read the corpus and (re)generate voice.md. Preserves rules.md.| | /skill:voice-pull-emails | Pull recent sent emails via a Gmail MCP server. | | /skill:voice-pull-blog | Pull blog posts from a URL via web fetch. |

Shell helpers (in $VOICE_HOME/scripts/ after /skill:voice-init):

| Script | What it does | | ---------------------------- | ------------------------------------------------------------------------------------------------ | | pull_pr_descriptions.sh | Pull GitHub PR descriptions you authored. Splits into pure and assisted (AI-footer) buckets. | | pull_review_comments.sh | Pull GitHub PR review and conversation comments you authored. |

Drafting examples

/skill:voice email follow-up to a recruiter who hasn't replied in 2 weeks
/skill:voice pr-comment pushing back on a 1500-line generic helper that should be 4 small functions
/skill:voice review-summary close out a PR that was technically fine but scope-crept badly
/skill:voice slack ask the platform team for a CI pool with 32GB nodes

If you don't pass a register, the skill infers one from the topic and tells you what it picked.

How it works

                     ┌─────────────────┐
                     │   rules.md      │   ← you write this. authoritative.
                     │ (hard rules)    │
                     └────────┬────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
 corpus/emails/      corpus/github_prs/      corpus/blog/
 corpus/slack/       corpus/...
        │                     │                     │
        └─────────────────────┼─────────────────────┘
                              │
                     /skill:voice-distill
                              │
                              ▼
                       voice.md (style guide)
                              │
                              ▼
                        /skill:voice
                       (draft anything)

• rules.md is policy. You hand-edit it. The package treats it as authoritative and applies every rule to every draft.
• corpus/ is data. The package reads from it for grounding (cadence, phrase choice, structural habits).
• voice.md is distilled summary. Generated by /skill:voice-distill. Refresh whenever the corpus grows materially.
• /skill:voice loads all three when drafting and pulls 3-5 register-matched samples from the corpus.

Corpus filtering

Voice modeling fails when the corpus is dominated by low-effort or AI-mediated text. The package applies these filters by default:

• Drop bodies under 30 characters unless clearly content
• Drop one-line acks ("LGTM", "ok", "thanks", "👍")
• Drop content with agent-footer signatures ("Generated with Claude Code", etc.)
• Drop forwards with no original commentary
• Drop self-notes (body is just a URL or a token)

Recent agentic-development output is not your pure voice. Even without an explicit footer, PR descriptions written collaboratively with an LLM tend to have heavy structure (## Summary, ## Test plan, acceptance-criteria tables, exhaustive checklists) and a different cadence. If you've been using AI in your dev loop, your last six months of personal-repo PRs are agent-mediated, not pure-you. Add those repos to the exclude_repo_regex arg of the GitHub scripts:

bash $VOICE_HOME/scripts/pull_pr_descriptions.sh alice 'alice/(my-side-project|prototype-x)'

Or after pulling, manually filter pr_descriptions.jsonl by repo and date.

Where things live

$VOICE_HOME/                              (default: ~/.claude/voice/)
├── rules.md                              (you edit; authoritative)
├── voice.md                              (generated by /skill:voice-distill)
├── manifest.md                           (what's been ingested, when)
├── .gitignore                            (corpus/ ignored by default)
├── corpus/
│   ├── emails/<YYYY-MM>.jsonl
│   ├── blog/all_posts.md
│   ├── github_prs/
│   │   ├── pr_descriptions.jsonl
│   │   ├── pr_descriptions_pure.jsonl
│   │   ├── pr_descriptions_assisted.jsonl
│   │   └── review_comments.jsonl
│   └── slack/<workspace>.jsonl           (manual export)
└── scripts/
    ├── pull_pr_descriptions.sh
    └── pull_review_comments.sh

Privacy

• The default .gitignore in $VOICE_HOME excludes corpus/ and all .jsonl files. Sent email, work-repo PR comments, and Slack DMs are personal/employer-sensitive content; never commit them to a shared repo.
• If you want to back up your corpus, use a private personal repo and only commit if you're sure no employer-confidential content is included.

Dependencies

• pi with this package installed
• Gmail MCP (optional; needed for /skill:voice-pull-emails). Any Gmail MCP server that exposes thread search and thread get with full content.
• gh CLI (optional; needed for the GitHub scripts). Authenticated against github.com. For private-org repos with SAML SSO, run gh auth refresh -h github.com -s repo,read:org and authorize for each org.
• jq (used by both shell scripts).

Why not fine-tune?

Voice fine-tuning needs ~1000-5000+ register-matched samples to meaningfully shift base behavior; below that you mostly get overfitting to the content of the corpus. Most individuals have under 200 substantive samples across all sources combined, and refresh cadence is too slow to make iteration practical (rule change requires retraining, not a 30-second rules.md edit). The exception worth considering: a fine-tune as a rewriter (input: rough draft, output: voice-aligned), with a few thousand draft/final pairs. Even then, RAG over voice.md plus this package's grounding samples typically gets you 90% of the way at zero training cost.

Relation to the Claude Code plugin

This is a faithful port of the my-voice Claude Code plugin. Same corpus layout, same templates, same scripts, same workflow. The only differences are harness-shaped:

• Claude commands/*.md → pi skills/<name>/SKILL.md, invoked as /skill:voice* instead of /voice*.
• Skill names drop the colon (voice:init → voice-init) per the pi/Agent-Skills name rules.
• ${CLAUDE_PLUGIN_ROOT} template/script references → paths relative to the skill directory (../../templates, ../../scripts).

Releases publish from CI with npm provenance.