Skip to main content
Glama

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@whalory

On 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.


NOTE

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 .mcpb extension with six tools, plus the claude.ai skill upload

Four more tools

No end-to-end test recorded

claude.ai

Skill upload (-claudeai.zip), with code execution on

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 .mcp.json and got no project folder.

Cursor

The skill folder, with the tools in .cursor/mcp.json

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 [source needed: …].

Voice profile

VOICE.md and voice.json hold a brand's tone, the words it uses and avoids, its spelling variant, and its limits. Whalory reads the profile on every task, along with the LEARNINGS.md note beside it.

Two languages

English defaults to US spelling, and a profile can switch to en-GB, en-AU, en-CA, en-NZ, en-IE, or en-IN. Persian gets half-spaces, Persian digits, Persian quotation marks, and the Persian forms of yeh and kaf.

Local linters

lint.py picks the language of each line and hands it to lint_fa.py or lint_en.py. They check AI tells, puffery, facts missing from the brief, spelling, sentence length, readability, and channel limits.

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 missing
  1. Read 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.

  2. 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].

  3. 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.

  4. 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.

  5. 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 warnings

The 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, and lint_en.py, with --format, --channel, --profile, --facts, --variant, --house-style, --json, and --fix. textcount.py counts graphemes, X-weighted characters, UTF-16 units, and SMS segments.

  • Self-tests: python skills/whalory/scripts/selftest.py runs the Persian, English, and MCP suites.

  • Plugin: the whalory-writer and whalory-editor agents, and eight commands: write, review, voice, lint, learn, lessons, hub, and feedback.

  • Tools: lint_text, lint_file, check_final, get_playbook, get_reference_section, and profile_lookup over MCP.

  • Rule updates: through the Hub client, the plugins fetch signed rule files once a day. hub_client.py status shows the rules in use, pin freezes them, and rollback returns to the previous set.

  • Autolint, if you want it: claude plugin install whalory-autolint@whalory lints 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 plugin marketplace add gilebehnam/whalory, then claude plugin install whalory@whalory

Claude Desktop

whalory-core-mcp-3.2.3.mcpb for the tools, and whalory-core-3.2.3-claudeai.zip in Customize > Skills for the method

claude.ai

Turn on code execution, then upload whalory-core-3.2.3-claudeai.zip in Customize > Skills

Codex

Copy skills/whalory into ~/.agents/skills/ and call it with $whalory

Cursor

Copy skills/whalory into .cursor/skills/, then add the tools in .cursor/mcp.json

VS Code with GitHub Copilot

Unzip whalory-core-3.2.3-agent-plugin.zip and add its folder to chat.pluginLocations

Gemini CLI

Unzip whalory-core-3.2.3-skill.zip into ~/.gemini/skills/, then confirm when Gemini asks to activate the skill

Any chat

Paste a prompt from whalory-core-3.2.3-paste.zip into the custom instructions

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.

  1. Lint. An error blocks delivery: an invented number, a wrong Persian letter form, or a broken channel limit. Warnings go to the editor.

  2. Blind review. The editor scores the draft against the brief on a 20-point rubric and returns fixes. The review command runs the same pass on any file or pasted text.

  3. 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".

  4. 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 updates turns this off, and WHALORY_HUB=0 turns 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 --fix saves a fixed copy next to the original, and --write fixes 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

Whalyom

Your entire marketing department inside Claude Code: 536 AI agents in 28 departments. Open source.

whalyom.com

Whalyon

A business health check: 40 statements, 8 areas, a report card that finds the root cause, not the symptom.

whalyon.com

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

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 tools
check_finalFinal check of approved copyA
Read-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 playbookA
Read-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 sectionA
Read-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 fileB
Read-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)A
Read-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 profileA
Read-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

    A3.6/5.0

    Scored across 6 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides writing guidance and mechanical lint checks to help AI clients draft or rewrite content in a specific natural voice.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Scores 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -