tells for developers
The same checks as the home page, as a command line tool, a library, a free API, a CI step and a connector for AI assistants. Checking runs locally with no model and no network. Only the rewrite calls a model.
Why we built it. On Nexugen, people and companies build their own web and mobile apps and find customers, and its AI writes a lot of the words. That AI kept writing like AI, so we built tells to catch it and made it free for everyone.
Install
npm i @nexugen/tells
The command it installs is tells. To try it without installing:
npx @nexugen/tells lint draft.md
In a project that has it:
npx tells lint docs/ --ci --fail-on warning
npx tells rewrite draft.md --write
In code:
import { lint, rewrite } from '@nexugen/tells';
const result = lint(draft, { register: 'casual' });
console.log(result.findings, result.human.missing);
In CI
Inline on the pull request, as GitHub annotations:
- run: npx @nexugen/tells lint docs/ --format github --ci
Add --fail-on warning to block a merge on warnings as well as errors.
Use it in Claude or ChatGPT
tells runs as an MCP server, so an assistant can check its own draft, fix the flagged sentences and learn your style. The remote server needs no sign in.
https://tells.nexugen.app/mcp
Claude (claude.ai and Claude Desktop)
- Open Settings, then Connectors, and choose Add custom connector.
- Name it tells and paste the server address above. Leave the sign in fields empty.
- In a chat, turn tells on from the tools menu and ask Claude to check its draft with tells.
Claude Code
claude mcp add --transport http tells https://tells.nexugen.app/mcp
ChatGPT
- Open Settings, then Apps and Connectors, then Advanced, and turn on Developer mode.
- Choose Create, name it tells, paste the server address above and pick No authentication.
- In a chat, pick tells from the tools menu and ask ChatGPT to check its answer.
For a custom GPT, import /openapi.json as an action. Its privacy policy is at /privacy.
On your own computer
The package also runs the server locally over stdio, so checking never leaves your machine. Add this to Claude Desktop's config file:
{
"mcpServers": {
"tells": { "command": "npx", "args": ["-y", "@nexugen/tells", "mcp"] }
}
}
The tools are check_text, fix_text and build_voice. Locally, fix_text uses your ANTHROPIC_API_KEY when it is set and the public API when it is not.
API
curl -s https://tells.nexugen.app/v1/lint -d '{"text":"Great question! It is robust."}'
curl -s -X POST https://tells.nexugen.app/v1/keys
Checking is free with no key. Endpoints are listed at /v1, and the OpenAPI description is at /openapi.json.
Free keys
The rewrite gives a few free tries a day to each address. A free key from POST /v1/keys raises that. Send it as Authorization: Bearer <key>. Keys are stored only as a hash.
Voice from the command line
tells voice build samples/*.txt -o voice.json
tells rewrite draft.md --voice voice.json
Tested on 15 public domain authors: a held-out passage was closest to its own author's profile 45% of the time (chance is 7%), and it outscored other people's writing with an AUC of 0.95. How it is measured.
Benchmark
tells looks for two things. Tells are habits to remove: dashes, contrast frames, closing slogans, stock openers, generic examples. Human signals are patterns people use far more than models: specific numbers, names and dates, first-hand detail, asides, uneven rhythm.
We tested it on 14,497 human samples written before 2022, from about 40 sources, and 3,347 answers from Claude Haiku, Sonnet and Opus to 1,358 prompts in 14 genres. A third of the prompts told the model to sound like a person. The final check used a held-out set that tells had never seen, fetched after tuning stopped and scored once.
Limits: texts under 60 words are judged by the rules alone, most model answers in the benchmark come from Claude, and answers from prompts that asked the model to write like a person were caught about 94% of the time. Method, data and results per source. To compare models, see the tells model ranking.
Badge
If your docs or README pass tells, you can say so.
[](https://tells.nexugen.app)
<a href="https://tells.nexugen.app"><img src="https://tells.nexugen.app/badge.svg" alt="Linted with tells" height="20"></a>
Every habit tells looks for
One habit on its own is reported as a hint. A warning or error stands when the text shows at least two different kinds of tell, or one kind plus a low human-pattern score. The severity below is what a rule reports once that holds. The JSON is at /v1/rules.
| Id | Name | Severity | Why it stands out |
|---|---|---|---|
dash | Long dashes | info | Models reach for the em dash constantly, and readers have noticed. Most people type a comma, a colon or a full stop. |
not-x-but-y | "It's not X, it's Y" | error | The contrast frame is the most recognised model habit there is. It invents a claim nobody made so it can knock it down. |
setup-reveal | A drumroll before the point | warning | A drumroll before the point. People who know the point just say it. |
rhetorical-qa | Asking and answering yourself | warning | Real questions are asked because the writer wants to know. A question the writer answers in the next breath is a format, not a thought. |
staccato | Short dramatic fragments | warning | Drama by punctuation. It reads like an ad voice-over, and models use it to fake emphasis. |
triad | Lists of three | info | Models default to threes because they sound complete. One real reason is usually stronger than three vague ones. |
sweeping-opener | A big, vague opening | warning | It delays the point and could open any post ever written. Readers skip it, and so the rest gets skipped too. |
slogan-ending | A slogan at the end | warning | The reader already got it. A closing slogan is the line most likely to be AI, and the easiest to cut. |
sycophantic-opener | Praising the question | error | This is the assistant voice. Nobody opens a reply to a colleague by praising the question. |
chatbot-closer | A chatbot sign-off | warning | An offer nobody asked for, written the same way every time. People end when they are done. |
assistant-leak | Leftover chatbot text | error | It is the clearest possible tell, and it usually means a prompt or a preamble got pasted along with the answer. |
ai-vocabulary | Words chatbots overuse | warning | Each one is fine on its own. Together they are the signature of generated text, and most of them are vague. |
hype | Hype words | info | Hype tells the reader how to feel instead of showing them why. It also reads as a sales voice. |
intensifier | Words that only add weight | info | These words promise sincerity or weight without adding any. Models sprinkle them everywhere. |
filler-transition | Filler transitions | info | Essay glue. It announces that a point is coming instead of making it. |
stock-hook | A stock social media hook | warning | Borrowed social-media formats. They signal that a template is running, not a person. |
hedge-stack | Too many hedges | info | One small hedge is honest. A pile of them is a model covering itself, and the sentence ends up saying nothing. |
corporate-excitement | Announcing your excitement | warning | Every launch post says it, so it says nothing. The news is the thing you shipped. |
whether-youre | Speaking to everyone at once | warning | It addresses everyone, so it speaks to no one. It is filler that models add to sound inclusive. |
lecturing | Lecturing the reader | info | Sharing what happened lets the reader draw the lesson. Telling them what to do reads as a thought-leader post. |
crowd-address | Talking to a crowd | info | Good writing talks to one person. Addressing a crowd sounds like a newsletter template. |
signposting | Describing the text instead of saying it | info | It describes the text instead of being the text. |
vague-attribution | "Experts say" with no source | info | Unsourced authority is a common model habit and a common way to make things up. |
tagline | A tagline | info | Slogans fail the scroll test: they could sit under any product. Specific claims do not. |
explainer | An explainer under a heading | info | Read once, ignored for ever. Generated pages put one under every heading. |
exclamation | Exclamation marks | info | One "Congrats!" is normal. Generated copy uses them on every line to fake enthusiasm. |
emoji | Emoji as decoration | info | Emoji bullets are a hallmark of generated posts and READMEs. |
hashtag | A row of hashtags | warning | A block of hashtags at the end of a post is a template habit. Generated social posts almost always add one. |
semicolon | Semicolons for rhythm | info | In short-form writing a semicolon usually joins two clauses for rhythm, a model habit. People write two sentences. |
scare-quotes | Quotes for emphasis | info | Quotes for emphasis read as sarcasm or as a model hedging a word it is not sure of. |
bold-mid-sentence | Bold words mid-sentence | info | Generated posts bold key phrases to look skimmable. In a short text it just shouts. |
title-case-heading | Title Case headings | info | Generated documents default to Title Case. Sentence case reads like a person wrote it. |
uniform-rhythm | Every sentence the same length | info | People write a long sentence, then a short one. Even rhythm across a whole passage is a strong statistical sign of generated text. |
validation-opener | Sympathy before the answer | warning | Generated advice almost always starts with sympathy before the answer. People on forums mostly start with the answer, or with a question. |
stock-warmth | Greeting card lines | info | The greeting-card lines generated messages to friends are built from. A friend writes one specific thing instead. |
bold-lead | Bold headings on every step | warning | Generated advice is laid out as bold-headed steps. People answering a question write paragraphs. |
unfilled-placeholder | A placeholder left in | warning | Models fill gaps with brackets and people paste them straight out. It is the fastest way to show a reader a template wrote to them. |
email-boilerplate | Form letter lines | warning | Form-letter lines. Generated emails are built almost entirely from them. |
benefit-cliche | Stock benefit phrases | info | Stock benefit phrases. They fill the space where the real benefit should be. |
so-you-can | "So you can" on every feature | info | Generated copy bolts a benefit onto every feature with the same connector. |
turn-x-into-y | "Turn X into Y" | info | One of the most reused headline shapes in generated marketing. |
fragment-triad | A slogan of three short phrases | warning | A slogan built from three noun phrases. It sounds finished and says nothing a reader can check. |
bold-line | Bold lines used as headings | info | Chat-style output fakes headings with bold lines. In an email, post or comment it reads as generated. |
summary-line | A summary at the end of every paragraph | warning | Models wrap each paragraph like a school essay. People move on once the point is made. |
list-everything | Everything in a list | info | Bullets are the default shape of generated replies. In a message to a person, sentences carry reasons and order better. |
bold-label-list | Bullets with bold labels | warning | This exact layout is one of the most recognisable shapes of chatbot output. |
pros-cons | Perfectly balanced pros and cons | info | Balanced halves look thorough and avoid a decision. People usually just say which one they would pick and why. |
no-point-of-view | No point of view | info | Someone wrote this for a reason. Text that never says who is speaking reads as generated or as a brochure. |
over-qualified | Vague amounts | info | These soften a claim until it says nothing. Models use them to stay safe. |
inflated-verb | Inflated verbs | info | Plain verbs are what people say out loud. Inflated ones are a staple of generated and corporate prose. |
generic-example | A generic example | warning | A generic example is a placeholder for a real one. People reach for the case they actually know. |
stock-courtesy | Support script lines | warning | Script lines from support templates. They read as no one in particular, which is the opposite of what an apology needs. |
cta-ending | A stock call to action | info | Generated posts end on the same handful of pushes. A person usually stops on the fact, or says plainly where to find it. |
looking-for-hook | "If you're looking for" | warning | An ad formula that guesses at the reader's problem. It reads as copy written for search engines. |
label-opener | A label to open with | info | Fine now and then, but models open nearly every message this way. |
parallel-slogan | Punchy parallel lines | warning | Ad-copy rhythm. It sounds punchy and says nothing specific. |
empty-adjective | Empty adjectives | info | Every product claims these, so they carry no information. |
headings-in-message | Headings in a short message | info | People do not put section headings in an email or a chat reply. Models do it by reflex. |
bold-overuse | Too much bold | info | When everything is bold, nothing is. Generated answers bold for skimmability by default. |
reassurance-frame | Reassurance before the answer | warning | This is how a chat assistant opens almost every how-to answer. A person who knows the answer starts with it. |
listicle-intro | Announcing a list | warning | The answer is announced before it is given, in words that fit any topic. People skip the announcement or say what the list is for. |
ordinal-sequence | First, second, finally | warning | A numbered list written out as sentences, the shape of a generated how-to. People who write steps in prose let the order show through the content. |
upbeat-close | An upbeat moral at the end | warning | The pep talk at the end of every generated answer. It could close any answer on any subject, which is how readers spot it. |