Whalory
Whalory's local MCP server provides copy QA, playbook/reference lookup, and brand voice profile discovery for Persian and English.
Lint pasted copy or supported files for AI tells, puffery, spelling, punctuation, sentence length, readability, facts, profile rules, and channel limits.
Run a final check on user-approved copy, with optional local Hub count recording only if the user enabled it.
Retrieve the best Whalory playbook for a task from an anchor or free-text English/Persian query.
Read sections from Whalory reference, profile, and channel data files.
Look up and normalize brand voice profiles from project, user, skill, starter, or Whalory defaults, including learnings and starter suggestions.
Operates locally over stdio; lint and lookup tools are read-only, idempotent, and make no network calls by default.
Whalory Core 3.2.3. Download versioned Core assets from the tagged release. Local tools work without an API key. Automatic Hub synchronization remains disabled; archive checksums are integrity checks, not publisher signatures.
Whalory gives the AI you already use a copywriter's working method and a voice profile for each brand. Its linters check English and Persian copy on your own machine.
Whalory reads the brief before it writes. It asks at most three questions, and only when an answer would change the text. It keeps to the facts you supplied and marks each gap with a bracket, such as [confirm: serving time]. Then the linters check the draft on your machine, and a blind editor pass reviews it. Whalory Core is free, under open licenses.
It has an install route for Claude Code, Claude Desktop, claude.ai, Codex, Cursor, Gemini CLI, and GitHub Copilot in Visual Studio Code (VS Code). Any other chat assistant can take it as a pasted prompt.
Latest release: Whalory Core 3.2.3 · Install guides for every host
In Claude Code, this repository is its own plugin marketplace:
claude plugin marketplace add gilebehnam/whalory
claude plugin install whalory@whaloryOn Windows, add --config python=python to the install command. Every other host is in docs/INSTALL.md.
Whalory Pro and Studio add every playbook, the market files, transcreation, four more agents, and four more MCP tools. Pro costs $29 once, and Studio $199 a year. International checkout isn't open yet: join the waitlist, and nothing is charged until it opens.
Whalory has no model of its own. It works inside the assistant you already use: your assistant writes, and Whalory brings the method, the voice profile, and the checks. The linters and the MCP server run on your machine and make no network calls. The study that will measure what Whalory changes is designed but hasn't run, so this page shows no scores.
Contents
Related MCP server: slop-guard
Where it installs
Keep the assistant you already use. Each route below is a package that the 3.2.3 release build produces. We call a route tested only after a dated end-to-end test. Until then, its guide says it was checked against the host's own documentation. The last column shows the latest test, run on the 3.0.0 build.
Host | Whalory Core (free) | Whalory Pro adds | Latest test record |
Claude Code | The plugin from this repository, with the writer and editor agents, eight commands, and the MCP tools; or the skill folder | Four more agents, three more commands, a private marketplace | Claude Code 2.1.278 loaded the plugin and connected its MCP server. The marketplace install had not been run. |
Claude Desktop | The | Four more tools | No end-to-end test recorded |
claude.ai | Skill upload ( | The full reference set | Not yet tested with a real upload |
Codex | The skill folder, or the Agent Plugins package | Three more commands, in the Agent Plugins package | codex-cli 0.145.0 loaded the skills. The plugin's MCP server started only from the legacy |
Cursor | The skill folder, with the tools in | A Cursor plugin with agents | No end-to-end test recorded |
VS Code with GitHub Copilot | The Agent Plugins package, or the skill folder | The full agent set | Neither plugin route had been tested when 3.0.0 was built |
Gemini CLI | The skill folder. An extension with agents is built, and its repository is not published yet. | The full agent set, in the extension | No end-to-end test recorded |
Any chat | Paste-in prompts of 1,500 and 4,000 characters, in English and Persian | An 8,000-character prompt; packs for Custom GPTs, ChatGPT Projects, Gemini Gems, and the Gemini app; editor and repository rules | Needs no install. No scripts run, so the check is manual. |
Hosts that read Agent Skills from .agents/skills/ can load the same folder. The full compatibility table, column by column, is on the site's download page.
What it is
Whalory is a set of files your assistant reads, plus a few small programs it can run. The model stays the one you chose.
Part | What it does |
Working method | Before it writes, Whalory settles the task, the channel, the reader, and the output language. It asks at most three short questions, each with a recommended answer. Reply "write" and it drafts at once. |
Playbooks | Each task has a playbook. Core covers captions, social posts, taglines, SMS, email, customer replies, product descriptions, UI microcopy, error states, about pages, style repair, reviews, and voice profiles. |
Three fixed rules | Nothing is invented: no made-up numbers, quotes, reviews, or results. No machine patterns, such as the straw-man contrast or the moral wrap-up. No claim goes out without evidence the brand can show; otherwise it gets a bracket like |
Voice profile |
|
Two languages | English defaults to US spelling, and a profile can switch to |
Local linters |
|
Blind editor | In the Claude Code plugin, a second agent reviews each draft. It sees the draft, the facts, the profile, and the format, never the writer's reasoning. On other hosts, the same model runs that review as a separate pass. |
MCP server | One Python file over stdio, with six tools in Core. It opens no sockets. It writes no files, apart from counts in the Hub folder while you have Hub statistics or packets on. |
Whalory Hub | It keeps the rules current between releases. The plugins start the Hub client when a session starts, and once a day it downloads rule files that Whalory signed. It checks every signature before the linters use them. Sharing counts with Whalory stays off unless you turn it on at your own terminal. |
How it works
the brief
│
▼
┌──────────────────────────────────────────────┐
│ your AI drafts with the Whalory method │ task, channel, reader, language
│ SKILL.md + playbook + voice profile │ at most 3 questions, facts only
└──────────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ deterministic lint, on your machine │ lint.py → lint_fa.py / lint_en.py
│ same text in, same findings out │ exit 0 clean · 1 errors · 2 bad input
└──────────────────────┬───────────────────────┘
▼
┌──────────────────────────────────────────────┐
│ blind editor pass │ sees the draft, facts, profile,
│ score table and fixes │ format; never the reasoning
└──────────────────────┬───────────────────────┘
▼
revise ──► lint again
│
▼
deliver the copy, then a note that starts with
"Diagnosis:" and lists what is still missingRead the assignment. Whalory settles the output language in a fixed order. Your instruction comes first, then the channel or market, the material you supplied, and the language of your request; the profile decides last.
Draft within the facts. The playbook sets the shape, and the profile sets the voice. A detail nobody supplied stays visible, as in
[confirm: weight].Lint. The same text always gets the same findings, so a rule either fires or stays quiet. Without Python, Whalory walks a manual checklist and says so in its note.
Review blind. The editor hasn't seen how the draft was made, so it reads it the way a client would. In the Claude Code plugin that editor is a second agent; elsewhere it's a separate pass of the same model.
Deliver. The copy comes first, then a short note on what changed and what you still need to confirm.
Features
One brief, three channels
A café opens an hour earlier. From that one set of facts come an Instagram caption, a text message, and a web page, each in the shape its channel needs. The start date nobody supplied stays a visible placeholder in all three.
The site's examples were written by the Whalory team to show the method, and each one carries a label that says so. They are not model output.
Read before the labels
You see two drafts of one brief, labeled A and B, and pick the one you would publish. Only then does the page show which one followed Whalory's method. The site collects no choices and publishes no win rate.
Try it on your phone
The home page runs the method on a prepared draft. Press Apply Whalory and each change arrives with its reason. It works at phone width, too.
A real linter run
Here is a short brief, and a draft that ignores it. The output below is copied from a real run of lint.py 3.1.0.
brief.txt
Tidy is a shared task planner for small teams. Free for up to 5 people. Paid plan: $6 per person per month. Syncs with Google Calendar.draft.txt
In today's fast-paced world, Tidy isn't just a planner. It's a game-changer that empowers teams to unlock their full potential. Trusted by 10,000 teams, Tidy is free for up to 5 people and syncs with Google Calendar!$ python skills/whalory/scripts/lint.py draft.txt --facts brief.txt
draft.txt:1:140 error en-fact-not-in-brief Number "10,000" is not in the facts; remove it, or bracket it: [source needed: …] "al. Trusted by 10,000 teams, Tidy is"
draft.txt warning en-bangs Exclamation marks: 1; limit 0
draft.txt:1:1 warning en-cliche-open Cliché "In today's fast-paced world"; start with the fact "In today's fast-paced world, Tidy isn't ju"
draft.txt:1:64 warning en-buzzword Buzzword "game-changer"; say what it does, for whom, with a number "lanner. It's a game-changer that empowers"
draft.txt:1:82 warning en-buzzword Buzzword "empowers"; say what it does, for whom, with a number "e-changer that empowers teams to unloc"
draft.txt:1:100 warning en-journey "unlock their full potential": use a concrete verb "owers teams to unlock their full potential. Trusted by 10"
draft.txt: [en] 3 sentences, 12.7 words on average, cap 25, grade 6.7, reading ease 69.3 · 1 errors · 5 warningsThe brief never mentions 10,000 teams, so the number is an error, and the linter exits with 1. A CI job fails at that point. The autolint hook never blocks an edit: it reports the error back to the assistant. To see every rule and format, run python skills/whalory/scripts/lint.py --rules.
What you get for free
Method: context detection, a question gate of at most three questions, and playbooks for the most common tasks. A task index matches requests in either language.
Voice: profile templates in both languages, Whalory's own voice as an example, and café and SaaS starter profiles per language. Profiles live in your project or in
~/.whalory/profiles/, so an update never overwrites them.Checks:
lint.py,lint_fa.py, andlint_en.py, with--format,--channel,--profile,--facts,--variant,--house-style,--json, and--fix.textcount.pycounts graphemes, X-weighted characters, UTF-16 units, and SMS segments.Self-tests:
python skills/whalory/scripts/selftest.pyruns the Persian, English, and MCP suites.Plugin: the
whalory-writerandwhalory-editoragents, and eight commands:write,review,voice,lint,learn,lessons,hub, andfeedback.Tools:
lint_text,lint_file,check_final,get_playbook,get_reference_section, andprofile_lookupover MCP.Rule updates: through the Hub client, the plugins fetch signed rule files once a day.
hub_client.py statusshows the rules in use,pinfreezes them, androllbackreturns to the previous set.Autolint, if you want it:
claude plugin install whalory-autolint@whalorylints content and locale files after each edit.
Editions and pricing
Edition | Price | For | What it adds |
Whalory Core | Free | Everyone, commercial work included | Everything in this repository |
Whalory Pro | $29, one-time | One person, with 12 months of new versions | Every playbook, with multichannel chains; every craft and market file; four more agents; ten MCP tools in all; every install pack |
Whalory Studio | $199 a year | Up to 5 people in one organization | Everything in Pro, for a shared repository or workspace that only those people can reach |
Pro update renewal | $15 | An existing Pro license | Another 12 months of new versions, on the same license key |
These prices are in US dollars, for buyers outside Iran. International checkout isn't open yet, so the pricing page has a waitlist and takes no payment, pre-order, or deposit. The opening will be announced in this repository. Paying with an Iranian bank card? The Persian page covers that checkout, which isn't open yet either.
A Pro version you receive keeps working after its 12 months. Whether Studio keeps working after its year isn't settled yet. The license agreement for Pro and Studio is still a draft, and its refund terms aren't decided yet.
Getting started
The latest release is 3.2.3, with Core archives and SHA256SUMS. The earlier stable baseline is 3.0.0. Read installation instructions and the host verification limits before installing.
You use | Start with |
Claude Code |
|
Claude Desktop |
|
claude.ai | Turn on code execution, then upload |
Codex | Copy |
Cursor | Copy |
VS Code with GitHub Copilot | Unzip |
Gemini CLI | Unzip |
Any chat | Paste a prompt from |
Python 3.8 or later runs the linters and the MCP server. Without Python, the skill still works and checks by hand.
To check the install, ask your assistant: Write a caption introducing [product]. You should get one to three short questions, or the caption with a note that starts with "Diagnosis:". Unknown facts stay in brackets.
The quality loop
Every draft goes through this loop before you see it. In the Claude Code plugin, a second agent does the review; on other hosts, the same model does it in a separate pass.
Lint. An error blocks delivery: an invented number, a wrong Persian letter form, or a broken channel limit. Warnings go to the editor.
Blind review. The editor scores the draft against the brief on a 20-point rubric and returns fixes. The
reviewcommand runs the same pass on any file or pasted text.Revise and lint again, for two rounds at most. A draft is ready at zero lint errors and a score of 17 or more. Without Python, the quality assurance (QA) line of the note says "QA: manual".
Deliver with a note. It says what changed and what is still open. In a high-risk industry, it also names what to confirm before publishing.
The linter exits with 0 when there are no errors, 1 when there are, and 2 on bad input. Any CI system can run it. Add --strict to fail on warnings, too. The skill's guide has a ready GitHub Actions job and a pre-commit hook: Continuous integration.
The benchmark
Status: pending. We have designed the study and fixed its protocol. No model has run yet, so there are no results.
Question: given the same client brief, does a model that follows Whalory write copy closer to a professional writer's? The comparison is the same model with the brief alone.
Design: 52 briefs, half English and half Persian, from low to high risk. The two conditions differ only in the skill, with three samples per brief and condition: 312 drafts and 156 blind pairs. People who didn't work on Whalory judge them, and so do AI models from other model families.
Decision rule: set in advance for each language. The outcome is better, worse, inconclusive, or no detectable difference.
Report: published whatever it shows, ties and losses included, with the model id and the date of the run.
We fixed protocol version 1.1 on September 28, 2026, before any run. The full design is on the site's evidence page.
Privacy and network activity
The linters, the MCP server, and the autolint hook run on your machine and make no network calls. No text you write leaves your machine through Whalory.
One part uses the network: the Hub client, which the plugins start when a session starts. Once a day it downloads signed rule files, and the request carries no identifier. Like any web server, the mirror that answers sees your IP address.
python skills/whalory/scripts/hub_client.py off updatesturns this off, andWHALORY_HUB=0turns off the whole Hub.Rule statistics and the weekly packet are off by default. They stay closed until Whalory opens them with a signed setting, after a legal review of their notices. Even then, only you can turn one on, by typing a code at your own terminal.
It changes your files only when you ask.
lint.py --fixsaves a fixed copy next to the original, and--writefixes the file in place.Your assistant is a separate service, and it handles your text under its own terms.
PRIVACY.md has the details: every switch, and what the Hub keeps on your computer.
Roadmap
Public 3.0.0 is the verified released baseline. The private 3.1.0 development precursor contains the canonical Hub implementation, final checks and user-approved lessons. The 3.2 line continues that source as public releases; 3.2.3 is the latest. See CHANGELOG.md for the corrected history.
Next:
Run the benchmark, and publish the report whatever it shows.
Publish the Gemini CLI extension in its own repository.
Open rule statistics and the weekly packet, after a legal review of their notices. See whalory-hub.
A dated end-to-end test on every host, recorded next to each install route.
Open checkout for Pro and Studio, international checkout included.
FAQ
Is Whalory free? Whalory Core is free, commercial work included, under open licenses: CC BY 4.0 for text, MIT for scripts. Pro and Studio add more playbooks and agents; their checkout isn't open yet.
Does it replace my AI model? No. Whalory is a set of files your assistant reads, plus a few small programs it can run. The model stays the one you chose.
Which AI tools does it work with? It has install routes for Claude Code, Claude Desktop, claude.ai, Codex, Cursor, Gemini CLI, and GitHub Copilot in VS Code. Any other chat assistant can take it as a pasted prompt.
Does my text leave my machine? Not through Whalory. The linters, the MCP server, and the autolint hook run on your machine and make no network calls. The only network part is the Hub client, which downloads signed rule files once a day and can be turned off.
Does it write in Persian (Farsi)? Yes. Persian gets half-spaces, Persian digits, Persian quotation marks, and the Persian forms of yeh and kaf, with its own linter. English defaults to US spelling, and a profile can switch to UK, Australian, Canadian, New Zealand, Irish or Indian English.
Will it make up numbers or reviews?
No. Nothing is invented: a claim the brand can't back gets a bracket like [source needed: …] instead.
More from Whalya
Whalory is made by Whalya, a product-led venture studio.
Product | What it does | Website |
Your entire marketing department inside Claude Code: 536 AI agents in 28 departments. Open source. | ||
A business health check: 40 statements, 8 areas, a report card that finds the root cause, not the symptom. |
Whalya was founded by Behnam Jafari Balalami. More about the studio: github.com/whalya-studio.
⭐ If Whalory helps your writing, star this repository. Stars help other writers and teams find it.
Contributing
We welcome reports of false positives, missing rules, host install notes, and fixes to the English or Persian references. Start with CONTRIBUTING.md. In short: open an issue with the exact text and the command, keep Python to the standard library, and run python skills/whalory/scripts/selftest.py before a pull request.
This repository is built from the Whalory source. The maintainers carry an accepted change into the source, and it arrives here with the next release, credited in the changelog.
Everyone who takes part agrees to the Code of Conduct. For questions, see SUPPORT.md.
Security
Please report a vulnerability privately through GitHub: Report a vulnerability. Don't open a public issue. The scope and the process are in SECURITY.md.
License
Whalory Core is free for everyone, commercial work included.
Scripts, meaning every file in a
scripts/folder, come under the MIT License.Everything else comes under Creative Commons Attribution 4.0. That covers the skill, the references, the profiles, the agents, the commands, and these documents.
The names and logos "Whalory", «والوری», "Whalya", and «والیا» aren't licensed. You may use them to credit Whalory, and a changed version takes a name of its own.
Text you write with Whalory is yours. You don't need to credit Whalory in it.
When you share Core, credit it like this:
Based on Whalory by the Whalya studio, https://github.com/gilebehnam/whalory, licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). [Unmodified / Modified: one line on what changed]The full terms are in LICENSE-CORE.en.md and LICENSE.en.md. Pro and Studio files aren't in this repository, and a separate paid license covers them.
Acknowledgments
Agent Skills and the Model Context Protocol, the open formats that let one folder serve many assistants.
Creative Commons and the MIT License, for the licenses.
Keep a Changelog and Semantic Versioning, for the changelog and the version numbers.
Contributor Covenant, for the Code of Conduct.
Shields.io, for the badges.
We wrote this page with Whalory, like all the copy on the Whalory website. Each section started from a short brief and passed the linter with zero errors. Then the same AI reread it in a separate pass and scored it at least 17 of 20. How we wrote the site
A Whalya product · © 2026 Whalya
Available Tools
6 toolscheck_finalFinal check of approved copyARead-onlyIdempotent
Final check of the copy the user approved: runs Whalory's checks and returns any remaining findings, in the same form as lint_text. Call it once when the user approves final copy. If the user turned on Whalory Hub statistics or weekly packets in their own terminal, it also records counts on this computer, never text, of which Whalory checks the user's own edits removed. With statistics, the user chose to send those counts weekly to Whalory's server in Iran; a packet leaves the computer only if the user posts it on GitHub.
Inputs: text (required), md, format, channel, +4 more. Returns: lang, stats, issues, passed, +2 more
get_playbookLoad a playbookARead-onlyIdempotent
Return the Whalory playbook section for a task (steps, questions, references, output, QA). Accepts a playbook anchor such as 'caption' or a free-text task in English or Persian; returns the best match and up to limit-1 alternatives.
Inputs: task (required), limit.
get_reference_sectionRead a reference sectionARead-onlyIdempotent
Read one section (or the contents list) of a Whalory reference file under references/ (method, fa/, en/), profiles/ or data/channels/. Long files: call without anchor to get the contents list first.
Inputs: path (required), anchor, max_chars.
lint_fileLint a fileBRead-onlyIdempotent
Lint a text, Markdown, HTML, CSV/TSV or locale file (json, po, arb, xliff, strings, strings.xml) inside an allowed folder. Locale keys and placeholders are never changed; CSV issues are keyed row/sku/column.
Inputs: path (required), md, lang, facts, +5 more. Returns: lang, path, stats, issues, +3 more
lint_textLint copy (Persian or English)ARead-onlyIdempotent
Check Persian or English copy against Whalory's rules (AI tells, puffery, spelling, punctuation, sentence length, readability, brand profile and channel limits). Language is detected per line unless set.
Inputs: text (required), md, lang, facts, +6 more. Returns: lang, stats, issues, passed, +2 more
profile_lookupFind the voice profileARead-onlyIdempotent
Find the brand voice profile in Whalory's order: project VOICE.md/voice.json/voice/VOICE.md, ~/.whalory/profiles/, the skill's profiles, the closest starter. Returns the normalized JSON profile, the learnings note and starter suggestions.
Inputs: name, industry, language, project_dir, +1 more. Returns: path, found, source, profile, +5 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The three lint-related tools overlap: check_final is explicitly described as returning findings 'in the same form as lint_text', and lint_file vs lint_text differ only in input source, so an agent may struggle to pick the right one. get_playbook and get_reference_section both read from Whalory's knowledge base with different anchors, which descriptions partially clarify but not decisively.
Five of six names follow a verb_noun pattern (lint_file, lint_text, get_playbook, get_reference_section, check_final), giving a predictable shape. profile_lookup breaks the convention with noun_verb ordering, a minor but visible deviation.
Six tools is well-scoped for a copy-linting and brand-voice guidance server: two lint entry points, one final gate, one profile resolver, and two knowledge retrieval tools. No tool appears redundant enough to drop, and none is filler.
Core lint-and-check workflows are covered, but there is no way to create, edit, or save a brand profile (profile_lookup only reads and suggests starters) and no tool to enumerate available playbooks or reference files upfront. An agent must discover anchors by trial or by calling get_reference_section without an anchor, which is a notable gap.
Maintenance
Related MCP Connectors
DraftCheck: flags AI-writing patterns in prose with fix hints. Deterministic linter, not a detector.
Static linter for CLAUDE.md-style agent constitution files: 10 operational-guardrail checks.
Static linter for CLAUDE.md-style agent constitution files: 10 operational-guardrail checks.
Prose linter + AI-slop detector: weasel words, passive voice, hedging, and research-cited AI tells
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides writing guidance and mechanical lint checks to help AI clients draft or rewrite content in a specific natural voice.MIT
- FlicenseNot gradedqualityAmaintenanceEnables agents to analyze text strings or files for formulaic AI writing patterns, returning a 0–100 score, band label, specific violations with context, and concrete advice. It performs this rule-based linting locally without LLM judges or API calls.-
- FlicenseNot gradedqualityAmaintenanceScores prose from 0 to 100 for formulaic AI writing patterns using purely programmatic rules, with no LLM judge or API calls. Enables agents to lint text or files and receive a score, band label, specific violations with surrounding context, and concrete advice for each hit.-
- FlicenseNot gradedqualityAmaintenanceEnables agents to analyze inline prose or files on disk for formulaic AI writing patterns, returning a 0-100 score, band label, specific violations with context, and concrete advice. Uses purely programmatic, configurable rules with no LLM judge or API calls.-