patina looks for AI-sounding patterns in Korean, English, Chinese, and Japanese, then rewrites them without changing the claim. Use it as a skill for Claude Code, Codex CLI, Cursor, and OpenCode, or run it as a standalone Node.js CLI.

It is not a black-box paraphraser. patina is pattern-based and auditable: it shows what changed, why it changed, and whether the original claims were preserved.

Demo

Before (AI-sounding):

Coffee has emerged as a pivotal cultural phenomenon that has fundamentally transformed social interactions across the globe. This beloved beverage serves as a catalyst for community building, fosters meaningful connections, and facilitates cross-cultural dialogue.

After (/patina --lang en — same claims, AI packaging removed):

Coffee has quietly changed how people meet. Sit across from someone long enough, and something like a real connection tends to form — even between people from very different cultures.

MPS = 100 · cultural transformation ✓ · community building ✓ · meaningful connections ✓ · cross-cultural dialogue ✓

More demo slices

| Input type | AI packaging removed | Preserved meaning | |---|---|---| | Korean marketing | “혁신적인 솔루션”, “새로운 패러다임” | 30 Notion templates, workflow fit, copy-and-edit usage | | Academic | “획기적인 성과”, broad significance claims | 60 GitHub projects, 72h→10m setup time, p<0.01, limits noted | | Technical | “핵심적인 역할”, future-standard hype | GPU management, one-command provisioning, 5× result caveat |

Try it quickly: 30-second terminal demo. More examples: Before/After Gallery (한국어). Brand assets: logo, icon, social preview, and before/after card. Usage notes: BRANDING.md.

At a Glance

| | | |---|---| | 160 patterns | 40 KO + 40 EN + 40 ZH + 40 JA (each incl. 8 score-only viral-hook) — see PATTERNS.md | | Editing hotspot recall | 91% Korean [84.0–95.4%] (n=100) / 76% English [66.7–83.3%] (n=100), binomial 95% CI | | Benchmark report | Reproducible ko/en/zh/ja suspect-zone benchmark: latest.md · latest.json · detector comparison | | False positives | 13–25% point-estimate range across human registers (not a CI; boundary intrinsic to encyclopedic register, documented) | | Modes | rewrite · audit · score · diff · ouroboros | | Free tier | Yes — via codex CLI (no API key) | | Determinism | Scoring formula is deterministic; LLM severity assignment ±8–10 pt per run (scoring.md §8) | | License | MIT |

Quick Start

As a Claude Code or Codex CLI skill

curl -fsSL https://raw.githubusercontent.com/devswha/patina/main/install.sh | bash

The installer wires patina into Claude Code, Codex CLI, Cursor, and OpenCode. It resolves the repository HEAD to a concrete commit before checkout; set PATINA_REF=<tag-or-full-sha> when you need a fully pinned install. Then:

/patina --lang en

[paste your text here]

Rewrite with a specific tone:

/patina --tone narrative

[paste your essay draft here]

Auto-detect and apply the best-fit tone:

/patina --tone auto --lang en

[paste your text here]

As a standalone CLI

Requires Node.js ≥ 18. After the npm release is cut, use the package directly:

npx patina-cli init --defaults
npx patina-cli doctor
npx patina-cli --lang en input.txt

Until then, or when you want to hack on the repo:

git clone https://github.com/devswha/patina.git
cd patina && npm install && npm link
patina --lang en input.txt

Or try stdin after linking:

printf '%s\n' 'Coffee has emerged as a pivotal cultural phenomenon that has fundamentally transformed social interactions across the globe.' \
  | patina --lang en --backend codex-cli

🆓 No API key required if you have any of codex, claude, or gemini CLIs logged in. Pick one with --backend codex-cli | claude-cli | gemini-cli, declare an explicit fallback chain such as --backend claude-cli,codex-cli, or let the model heuristic route automatically (--model claude-* → claude-cli, etc.). See AUTHENTICATION.md for the full backend list.

CI integrations

Patina also ships a no-key, deterministic CI check for prose review:

# .github/workflows/patina.yml
steps:
  - uses: actions/checkout@v6
  - uses: devswha/patina-action@main # use @v1 after npm publish + action tag
    with:
      patina-package: github:devswha/patina # remove after patina-cli@latest is on npm
      report-threshold: 30
      comment: true

Docker image publishing is tracked separately from the npm release path. Until the GHCR image is published, build the local image when you need a container:

docker build -t patina:local .
printf '%s\n' 'Coffee has emerged as a pivotal cultural phenomenon.' \
  | docker run --rm -i -e PATINA_API_KEY patina:local --lang en --provider openai

Pre-commit, Husky, Lefthook, Docker, and release workflow notes live in docs/integrations/.

Intended Use

Use Patina for post-AI editing, audit trails, and voice cleanup when the author is allowed to use AI assistance. It does not promise that text was “originally human,” and it should not be used for academic honor-code evasion, publisher disclosure circumvention, plagiarism laundering, or detector-bypass claims. See ETHICS.md.

Modes

patina --lang <ko|en|zh|ja> [mode] [--profile <name>] input.txt

| Flag | What it does | |------|-------------| | (default) | Rewrite | | --audit | Detect AI patterns only | | --score | 0–100 AI-likeness score with category breakdown | | --score --exit-on <n> | Keep CI strict: exit code 3 when overall > n (--gate is kept as an alias) | | --diff | Show changes pattern by pattern | | --ouroboros | Iterate the rewrite until score converges (with MPS rollback) | | --lang <ko\|en\|zh\|ja> | Select language (default: ko) | | --profile <name> | Tone preset: blog, academic, technical, formal, social, email, legal, medical, marketing, narrative, instructional, casual-conversation, code-comment, commit-message, release-notes | | --tone <name> | Tone category: casual, professional, academic, narrative, marketing, instructional, auto | | --batch | Treat positional args as a list of files (e.g. --batch docs/*.md) | | --format json\|text\|markdown | Select machine-readable JSON, plain text, or default Markdown output | | --quiet | Suppress status, warning, and progress logs on stderr | | --json-logs | Emit stderr logs as NDJSON with level, event, model, and latency_ms fields | | --prompt-mode strict\|minimal\|auto | Choose full pattern-pack prompting, compressed prompting, or backend-aware auto | | --variants <1-5> | Generate multiple rewrite variants with the same facts and meaning anchors |

patina --help for the full flag list. patina doctor --json checks Node/backend/tmux/API-key readiness without making an LLM call, and patina init writes a project .patina.yaml.

Dev-native profile shortcuts are available for Markdown-heavy engineering workflows: code-comment tightens inline comments/docstrings, commit-message rewrites Git history text around intent and verification, and release-notes turns changelog bullets into user-impact notes with migration risks visible.

Score-only patterns

--score and --audit measure a slightly broader set of signals than --rewrite does. The viral-hook packs (ko/en/zh/ja-viral-hook, 8 patterns each: shock-number hooks, clickbait closings, source-skipping authority claims, breath-optimized short-sentence stacking, hyperbolic engagement lexicon, fake-stat citations, stacked credentials, future-self/parasocial promises) are detection-only.

They appear in score and audit output so the benchmark matches human intuition for SNS-style marketing copy across all four languages. --rewrite/--diff/--ouroboros skip them because those signals are often intentional rhetoric. Real-world demos: examples/viral-hook/.

Prompt-mode tuning (v3.11)

--prompt-mode strict|minimal|auto lets you trade off between the full pattern packs (~34KB structured prompt) and a compressed casual instruction (~3KB). auto picks per backend — Gemini does better on minimal (it gets over-constrained by long structured prompts), while Claude leverages the full packs and Codex is roughly insensitive. case-05 documents the A/B.

Multiple stylistic variants (v3.11)

--variants <1-5> asks the model for N voice variants of the rewrite in one call (e.g., V1 casual, V2 direct, V3 measured) — facts, numbers, and causation stay identical across variants. Each comes back as ## Variant N so you can pick the voice you want.

Short-text scoring boost (v3.11)

For inputs ≤200 chars or ≤3 paragraphs, register-sensitive categories (language, style, viral-hook) get a 1.5× severity multiplier so single-paragraph voice shifts surface in the score. case-04 found these were undercounted by the long-text formula.

Self-audit isolation (v3.11)

In rewrite mode, the model emits its self-audit notes inside [SELF_AUDIT]/[/SELF_AUDIT] tags wrapped around a [BODY]/[/BODY] block (or [VARIANT n] blocks when --variants > 1). patina strips the audit before showing the user, so raw output is clean — earlier versions sometimes leaked phrases like "남아 있는 AI 티" or "Phase 3" preambles into the user-facing text.

Machine-readable output and exit codes

--format json wraps every mode in a stable envelope with overall, categories[], tone, mps, gateResult, and the cleaned output body. --json-logs keeps stderr machine-readable as NDJSON, while --quiet silences status/warning/progress logs for scripts that only want stdout. --format markdown is the default; --format text keeps the user-facing body without the YAML tone footer. Exit codes are standardized in EXIT-CODES.md: 0 success, 1 runtime/backend, 2 input/usage, 3 score gate exceeded, 4 MAX MPS fallback/all-candidates-failed.

Score weight drift detection (v3.11)

--score runs cross-check the Weight column the model emits against your config's category-weights. If the model invents a category (e.g., discord) or substitutes a different number, [patina] warnings hit stderr — observability only, the weight check itself doesn't alter the score. A deterministic shadow score from src/features/* is also recorded; when it differs from the LLM score by more than 20 points, patina warns and uses the more pessimistic value for gates.

--save-run <dir> now writes manifest schema v2: result entries include prompt and response hashes, available input/output token counts, temperature/seed, score details, per-call cost when a provider returns it, and Ouroboros iteration logs.

For repeat benchmarks, opt into the HTTP response cache with --cache <dir> or PATINA_CACHE_DIR. Cache keys include prompt, model, temperature, and API host; --cache-ttl <sec> controls expiry and --no-cache bypasses it for fresh runs. Patina prints hit/miss/write stats at the end of cached runs.

Use --voice-sample <path> or voice-sample: <path> in config to anchor rewrites to 1–3 paragraphs you wrote. Profile and tone still set the requested register; the sample only teaches cadence, specificity, POV, and sentence texture, and the prompt explicitly forbids importing sample facts.

Tones

--tone selects a named voice axis applied on top of pattern rewriting. Resolution order: --tone CLI > tone: config > profile: config.

| Tone | Intended for | Key behaviors | |------|-------------|---------------| | casual | Blog posts, social content, personal notes | Contractions, first-person, emoticons OK, low formality | | professional | Work emails, reports, business writing | Clear and concise, formal but not stiff; legal/medical sub-profiles force fidelity floor | | academic | Papers, research summaries, technical analysis | Objective, evidence-oriented, minimal first-person | | narrative | Personal essays, memoir, experience-based writing | First-person anchor, scene detail, emotional presence, time flow | | marketing | Ad copy, landing pages, product announcements | Short impact sentences, persuasive, CTA-friendly | | instructional | Tutorials, how-to guides, technical docs | Imperative verbs, numbered structure, hedging suppressed |

--tone auto runs heuristic detection (lexical + structural signals) and selects the best-fit tone. zh/ja with any tone (including auto) emits a warning and falls back to profile-only mode — Phase 4.5b heuristics only cover ko/en.

MAX mode

Run the same text through Claude, Codex, and Gemini independently. The lowest AI-score result that passes MPS ≥ 70 wins:

/patina-max

[paste your text here]

/patina-max uses tmux panes for parallel local-CLI dispatch when dispatch: omc is enabled. If tmux is unavailable, pass --dispatch direct for the no-tmux path; it runs the selected models sequentially and can take roughly one model timeout per model. When dispatch: omc falls back automatically outside tmux, Patina prints the expected sequential-vs-parallel wall-clock warning.

Standalone CLI MAX (patina --models ...) caps HTTP fanout at min(models, 3) by default to avoid quota storms on free-tier providers. Pass --max-concurrency <n> to tune the cap, or --max-concurrency 0 only when you intentionally want unlimited parallel requests.

How It Works

Input
  ↓
[Step 4.5]   Semantic anchor extraction (claims, polarity, causation, numbers)
[Step 4.6]   Stylometric pre-pass (burstiness CV + MATTR; zh/ja character-token fallback)
[Step 4.7]   AI-lexicon overlap (~108 EN / 102 KO entries)
[Phase 1]    Structure scan + anchor verification
[Phase 2]    Sentence rewrite + anchor verification
[Phase 3]    Self-audit (polarity, regression, MPS)
  ↓
Natural-sounding text (meaning verified)

If meaning drifts at any verification step, the change is retried or rolled back.

Calibration (500-paragraph corpus, reproducible via .omc/research/v3_8_remeasure.py): 76% editing-hotspot recall on HC3 ChatGPT (en) [66.7–83.3%] and 91% on paired ko/AI corpus [84.0–95.4%], each n=100 with binomial 95% CI. Human-prose false positives are reported separately as a 13–25% point-estimate range across registers, not as a confidence interval. Acceptance gates: AI ≥ 75%, max FP ≤ 25%. See stylometry.md for the algorithm.

Configuration

# .patina.default.yaml
version: "3.11.0"
language: ko              # ko | en | zh | ja
profile: default
output: rewrite           # rewrite | diff | audit | score
tone:                     # casual | professional | academic | narrative | marketing | instructional | auto
max-models: [claude, gemini]

Pattern packs are auto-discovered by language prefix. .patina.yaml in the working directory overrides defaults. List keys that extend detection (blocklist, allowlist, skip-patterns) merge additively across default/global/project configs; provider lists such as max-models replace so users can choose an exact backend set.

Documentation

• Cookbook — practical recipes (Hugo batch scoring, GitHub Actions, MAX-mode comparison, false-positive triage, custom profiles, pre-commit)
• Glossary — short definitions for MPS, fidelity, burstiness, MATTR, modes, and other recurring terms
• Demo — terminal transcript and multi-genre before/after snapshots
• Patterns — full 160-pattern catalog
• Authentication (한국어) — backends, providers, free-tier setup
• GitHub Action — PR hotspot comments without a live model key
• Pre-commit — pre-commit, Husky, and Lefthook score-only recipes
• Docker — GHCR image usage and release tags
• Release workflow — npm provenance + GHCR publishing checklist
• CLI Contract — score gate, JSON/text/Markdown output, and automation-safe surfaces
• Flag Parity — standalone CLI vs /patina vs /patina-max option support
• Exit Codes — process code contract for CI and editor integrations
• Ethics — intended use, non-use, and disclosure stance
• FAQ (한국어) — detector-bypass concerns, MPS, false positives, contribution starting points
• Comparison — factual comparison with common paraphraser/humanizer tools
• Branding — canonical logo/social assets and OG setup notes
• Design — product/brand source of truth for repo-native SVG and README surfaces
• Roadmap — quality, benchmark, product, community, and launch priorities
• Benchmark Report — latest reproducible suspect-zone benchmark summary
• Detector Comparison Harness — offline/manual comparison protocol for third-party detectors
• AI/Human Metrics Research — benchmark design notes for measuring AI-like writing signals
• 2025+ Re-baseline Plan — evidence gate before broader model-era claims
• Launch Copy — Show HN, Reddit, X, Korean community drafts
• Stylometry — burstiness + MATTR + AI-lexicon algorithm
• Scoring — AI-likeness + fidelity + MPS
• Changelog — release notes and methodology
• Contributing (한국어) — pattern submissions, false-positive triage, benchmark fixtures, versioning
• Governance / Maintainers — lightweight project decision rules

Acknowledgements

Inspired by oh-my-zsh's plugin architecture (patterns are plugins, profiles are themes), Wikipedia's "Signs of AI writing" catalog, and blader/humanizer.

License

MIT