Skip to main content

negaresh (نگارش)

ci License: MIT

A Persian (Farsi) writing guide for AI assistants and editors. It has three parts that work together or alone:

  • A rule set: 163 rules for Iranian standard Persian. They cover sentence structure and natural word order, verb tense and mood, paragraph flow, removing translated or machine-like Persian, grammar, usage, punctuation, numbers and citations, Academy orthography (نیم‌فاصله), and meaning preservation. Each rule has a test, examples, and a citation to the book it comes from.
  • A skill (standard Agent Skills SKILL.md folder) for Claude, Codex and other agents: how to write, copyedit, proofread or naturalize (روان‌سازی) a Persian text with the rules.
  • An MCP server (stdio and Streamable HTTP) for Claude, ChatGPT, Codex, Gemini CLI, Cursor, VS Code and any MCP client: deterministic checks (Arabic letters, digits, spacing, half-spaces, quotes, variant spellings, listed calques, and sentence shapes typical of machine Persian), rule search, and validation of edits before they are applied.

Status: draft (0.2.0). No human editor has approved the rules yet. Use them as suggestions and check important text yourself.

راهنمای نگارش فارسی برای دستیارهای هوش مصنوعی و ویراستاران: ۱۶۳ قاعده دربارهٔ ساخت جمله، ترتیب طبیعی اجزا، زمان و وجه فعل، پیوند بندها، زدودن نثر ترجمه‌ای و ماشینی، دستور، کاربرد، نشانه‌گذاری و دستور خط فرهنگستان؛ با یک مهارت (skill) برای Claude و یک سرور MCP محلی برای بررسی‌های مکانیکی. همهٔ قاعده‌ها پیش‌نویس‌اند.

Sources

The rules were built from five books: the Academy's «دستور خطّ فارسی» (1401), Anvari and Ahmadi-Givi's «دستور زبان فارسی» 1 and 2, Arzhang's «دستور زبان فارسی امروز», and Samiee's «نگارش و ویرایش». The author bought the books, scanned them with OCR, extracted the rules, and rewrote and tuned them to the author's needs. The books are not included, and the skill and server cannot read or search them; the skill applies the rules, not the books. Full titles are in NOTICE.md.

What it does

Task Ask for What happens
Write «این را به فارسی بنویس» / "write this in Persian" The model writes with a real subject and a finite verb for each action, no stock frames, natural order and tense.
Copyedit «ویرایش کن» Grammar, usage and spelling are fixed. Sentences with machine or translated shapes get a proposed rebuild.
Naturalize «روانش کن»، «طبیعی‌ترش کن»، «ترجمه‌ای است» Sentences and paragraphs are rebuilt from their meaning. Facts, hedges, actors, numbers and names are kept.
Proofread «غلط‌گیری کن» Characters, spacing, half-spaces, spelling and punctuation only.
Ask «این درست است؟» The rule is found and cited.

Requirements

  • For the MCP server: Python 3.11 or later and uv (uvx must be on the PATH). The server needs no network access while it runs.
  • The skill and the rule set need nothing.

Install

The server command is the same everywhere:

uvx --from git+https://github.com/Aricept094/negaresh negaresh serve

Claude Code (plugin: skill and MCP server together)

In Claude Code:

/plugin marketplace add Aricept094/negaresh
/plugin install negaresh@negaresh

Or from a terminal:

claude plugin marketplace add Aricept094/negaresh
claude plugin install negaresh@negaresh

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config) and restart the app:

{
  "mcpServers": {
    "negaresh": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Aricept094/negaresh", "negaresh", "serve"]
    }
  }
}

For the skill, upload negaresh-skill.zip from the latest release under Settings → Capabilities → Skills.

Claude.ai

Upload negaresh-skill.zip from the latest release under Settings → Capabilities → Skills. The skill works without the server.

ChatGPT

Two ways, both in clients/chatgpt: an MCP connector in developer mode (run the server with --http behind an HTTPS tunnel), or a custom GPT with the rule files as knowledge.

Codex CLI

codex mcp add negaresh -- uvx --from git+https://github.com/Aricept094/negaresh negaresh serve

For the skill, copy skills/negaresh to ~/.codex/skills/negaresh.

Gemini CLI

gemini extensions install https://github.com/Aricept094/negaresh

Cursor

Install in Cursor, or add the JSON block above to ~/.cursor/mcp.json.

VS Code

Install in VS Code, or:

code --add-mcp "{\"name\":\"negaresh\",\"command\":\"uvx\",\"args\":[\"--from\",\"git+https://github.com/Aricept094/negaresh\",\"negaresh\",\"serve\"]}"

Any other MCP client

  • stdio: uvx --from git+https://github.com/Aricept094/negaresh negaresh serve
  • Streamable HTTP: uvx --from git+https://github.com/Aricept094/negaresh negaresh serve --http --port 8000, then connect to http://127.0.0.1:8000/mcp. Use --allowed-host <name> for a proxy or tunnel host.
  • With pip: pip install git+https://github.com/Aricept094/negaresh, then negaresh serve.

Skill only (any client that reads Agent Skills)

The skill is a standard SKILL.md folder: skills/negaresh. Copy it into the client's skills folder (~/.claude/skills/, ~/.codex/skills/, or the client's own location).

Rule set only

  • corpus/rules/*.json: the rules as JSON (one array per category).
  • docs/RULEBOOK__NEEDS-INPUT.md: the full rule book in Persian.
  • corpus/lexicon/: variant spellings, listed expressions and sentence-shape patterns.

MCP tools

Tool Use
search_rules Find rules by Persian or English words.
get_rule One rule in full.
get_profile Conventions for a kind of text (academic, journalistic, literary, ...).
check_mechanics Checks M01 to M16. It returns findings with exact offsets, candidate patches, and a low-risk auto_patch_set.
validate_patches Checks that a set of edits applies cleanly and leaves URLs, code and other protected text unchanged.
search, fetch Over HTTP only: the search-and-read pair that ChatGPT connectors use.

All tools are read-only. The server stores no text on disk. Each call takes up to 12,000 Unicode code points.

Command line

negaresh doctor
negaresh check draft.txt --profile academic
negaresh search "نیم‌فاصله می"

Rule families

Prefix Family Rules Main sources
ORT Orthography and spacing 44 Academy «دستور خطّ فارسی» (1401)
GRM Grammar, word order, tense and mood 39 Anvari and Ahmadi-Givi 1 and 2; Arzhang; Samiee
USG Usage and calques 23 the three grammars; Samiee
STY Style and sentence building 19 Samiee; editorial synthesis
PUN Punctuation and characters 18 Samiee
TRM Numbers, dates, citations, notes, names 9 Samiee
INT Meaning preservation 6 Samiee; editorial synthesis
DSC Paragraphs and discourse 5 Samiee

Each rule has a severity (error, convention, advisory) and an evidence class. sourced rules name the book and page they come from; editorial_synthesis rules are editorial practice and are offered as suggestions only.

Edit the rules

  1. Edit the JSON in corpus/rules/.
  2. Run python tools/build.py. It validates the corpus and regenerates the bundle, the skill references and the rule book.
  3. Run pytest.

Do not edit generated files: src/negaresh/data/corpus.json, skills/negaresh/references/rules-*.md, docs/RULEBOOK__NEEDS-INPUT.md.

To make the release files (wheel, skill zip, clean folder): python tools/package.py.

Limits

  • The rules are drafts. No human editor has approved them.
  • The mechanical checker sees characters, listed expressions and a few sentence shapes. No finding does not mean that the prose is natural. Sentence and paragraph rebuilding is done by the model with the rules.
  • The «می» half-space check uses a closed list of verb stems.

Licence

MIT. See LICENSE.

Metadata

Release files for negaresh 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for negaresh 0.2.0
File Size Uploaded Provenance Actions
negaresh-0.2.0.tar.gz 159.6 kB With provenance Details for negaresh-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for negaresh 0.2.0
File Interpreter ABI Platform Actions
negaresh-0.2.0-py3-none-any.whl Python 3 none any Details for negaresh-0.2.0-py3-none-any.whl

Total release size: 313.8 kB

Release files / negaresh-0.2.0.tar.gz

Download URL negaresh-0.2.0.tar.gz
Size 159.6 kB
Tags Source
SHA-256 checksum
How to use checksums
0bb903a3a7e51cb184f52d530b595e2f08bae8bd60c4b95d55debf1087d2753f
BLAKE2b-256 checksum
How to use checksums
6bb377a0f739c4e4823b400c880d541a5e0995d99ce97aebf510c45c69aa4ec0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / negaresh-0.2.0-py3-none-any.whl

Download URL negaresh-0.2.0-py3-none-any.whl
Size 154.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
49e5dcf6008baebf55994aa844928e9bf21e2031e4869d18bdbf89750bd6cff8
BLAKE2b-256 checksum
How to use checksums
dca398ab3a809c0ed4dc1ac1980218e73685ce5ca3deb166816c1ec212614e5a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for negaresh 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for negaresh-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page