Poly Series

PolyScribe

Open Source

GitHub-native release editor. Ingests commits, PRs, and diffs to draft polished release notes and changelog sections.

Quick start

Start with the primary command, then continue with the full workflow below.

npm install -g @polyscribe/cli

Problem

Writing release notes by hand means manually triaging every merged PR, commit, and diff to figure out what actually changed - tedious, error-prone, and the first thing skipped when the release train is moving. Generic AI changelog generators fabricate notes from a model's guess instead of the repo's actual git history, so release notes drift from reality and users can't trust them. Engineering teams end up with either a wall of raw commit messages or marketing fluff, no structure by contribution type, and no way to keep CHANGELOG.md in sync with the GitHub Release. Publishing is a separate, manual chore: copy notes into the release UI, and repeat the whole dance every release.

Solution

PolyScribe ingests the raw source of truth - commits, PRs, and diffs for a git ref range - and drafts polished, structured release notes organized by contribution type (features, fixes, breaking changes, chores). It is a GitHub-native CLI (polyscribe) with an MIT-licensed core (@polyscribe/core) and CLI (@polyscribe/cli) that work offline with your own LLM key - no vendor lock-in, no cloud dependency. The architectural choice is human-in-the-loop publishing: PolyScribe does the grunt work of drafting and structuring, but a human reviews, edits, and approves before anything ships; --dry-run previews, --output files, and --write changelog updates support a full draft to review to publish workflow. When a GITHUB_TOKEN is provided, PR metadata (titles, descriptions, labels, review comments) enriches the draft for far more accurate notes.

How it works

Install the CLI globally (npm install -g @polyscribe/cli) or run it via npx without installing (npx @polyscribe/cli --help).

One-time setup: run polyscribe config init to create .polyscribe.yml in the current directory, then export your LLM key (OPENAI_API_KEY or ANTHROPIC_API_KEY) and optionally GITHUB_TOKEN for PR enrichment.

Run preflight checks: polyscribe doctor validates API keys, git repo, and config; polyscribe validate-config checks the .polyscribe.yml schema.

Draft release notes from a git ref range: polyscribe draft --from v0.1.0 --to HEAD; add --output RELEASE.md to write to a file, --tone technical to switch voice, or --json for structured output in CI.

Update or preview the changelog: polyscribe changelog --from v0.1.0 --to HEAD prints the body; --version 0.2.0 --write inserts a new section under [Unreleased]; --dry-run shows the unified diff without writing; --notes RELEASE.md uses an existing markdown body and skips the LLM.

Internally, PolyScribe loads .polyscribe.yml, resolves the git ref range, collects sources (commits, PRs, diffs) with optional GitHub enrichment, and calls the configured LLM to produce structured sections and rendered markdown.

Publish to GitHub Releases after human review: polyscribe publish --version v0.2.0 --notes RELEASE.md creates or updates the release. Debug raw sources anytime with polyscribe sources.

Technical architecture

Each handoff carries structured context through the product's execution path. Hover a node to inspect its role.

Git Range Ingest

Step 1: Git Range Ingest receives structured context from the prior stage and prepares it for the next handoff.

Diff Analysis

Step 2: Diff Analysis receives structured context from the prior stage and prepares it for the next handoff.

PR Enrichment

Step 3: PR Enrichment receives structured context from the prior stage and prepares it for the next handoff.

Commit Categorization

Step 4: Commit Categorization receives structured context from the prior stage and prepares it for the next handoff.

LLM Drafting

Step 5: LLM Drafting receives structured context from the prior stage and prepares it for the next handoff.

Human Review

Step 6: Human Review receives structured context from the prior stage and prepares it for the next handoff.

GitHub Publish

Step 7: GitHub Publish receives structured context from the prior stage and prepares it for the next handoff.

When to use

Regular releases where hand-writing notes is a recurring time sink for engineering teams.
Any repo where you want release notes that reflect real git history (commits, PRs, diffs) instead of model guesses.
Keeping CHANGELOG.md and GitHub Releases in sync without copy-paste drift.
Releases needing different voices for different audiences - technical vs. marketing tone from the same sources.
CI pipelines that need structured (--json) or previewable (--dry-run) release drafts.
Teams that want AI drafting but insist on human approve-to-publish for what ships.

Not for

Repos where you don't follow meaningful ref-range tagging (no tags - no natural --from ranges).
When you need perfect PR-level detail without a GITHUB_TOKEN - enrichment falls back to commit messages only.
Very large releases (500+ commits) on slow providers - drafting can take 30-60s; use --json in CI.
Single-branch teams writing CHANGELOG.md concurrently - --write modifies in place, so concurrent branches hit standard git merge conflicts.

Features

Commit and PR ingestion - parses commits, diffs, and PR metadata for a ref range; no manual triage

Structured draft generation - release notes organized by contribution type (features, fixes, breaking changes, chores)

Changelog management - write, preview (--dry-run), or update CHANGELOG.md with formatted sections

GitHub Release publishing - create and update GitHub Releases with your reviewed notes

Tone control - --tone technical for developer-facing releases, --tone marketing for user-facing announcements

Dry-run everywhere - every destructive command supports --dry-run for CI-safe previews

Multiple LLM providers - OpenAI or Anthropic, configured via POLYSCRIBE_LLM_PROVIDER

JSON output - --json flag exports structured data for CI pipelines and custom tooling

Source debugging - polyscribe sources lists every commit and PR in the range with raw metadata

Offline-first - core parsing and drafting works with local LLMs; no cloud dependency

Config persistence - .polyscribe.yml stores per-repository preferences

PR metadata enrichment - GITHUB_TOKEN adds titles, descriptions, labels, and review comments to drafts

Human-in-the-loop - full draft-review-publish workflow with preview/edit before anything ships

OSS-first packages - @polyscribe/core and @polyscribe/cli, MIT-licensed on npm

Install and usage

usage.sh

# Install globally (or npx without installing)
npm install -g @polyscribe/cli
npx @polyscribe/cli --help

# One-time setup
polyscribe config init
export OPENAI_API_KEY=sk-...          # or ANTHROPIC_API_KEY
export GITHUB_TOKEN=ghp_...           # optional -- enriches with PR metadata

# Preflight checks
polyscribe doctor
polyscribe validate-config

# Draft release notes from a ref range
polyscribe draft --from v0.1.0 --to HEAD
polyscribe draft --from v0.1.0 --to HEAD --output RELEASE.md
polyscribe draft --tone technical --json --output draft.json

# Update or preview the changelog
polyscribe changelog --from v0.1.0 --to HEAD
polyscribe changelog --version 0.2.0 --write
polyscribe changelog --version 0.2.0 --dry-run
polyscribe changelog --version 0.2.0 --write --notes RELEASE.md

# Publish to GitHub after human review
polyscribe publish --version v0.2.0 --notes RELEASE.md
polyscribe publish --version v0.2.0 --notes RELEASE.md --update

Architecture explorer

Problem

Solution

View on GitHub

PolyScribe

Quick start

Problem

Solution

How it works

Technical architecture

When to use

Not for

Features

Install and usage

Architecture explorer

Problem

Solution

Related products