tellsby the Nexugen team

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.

Server address
https://tells.nexugen.app/mcp

Claude (claude.ai and Claude Desktop)

  1. Open Settings, then Connectors, and choose Add custom connector.
  2. Name it tells and paste the server address above. Leave the sign in fields empty.
  3. In a chat, turn tells on from the tools menu and ask Claude to check its draft with tells.

Claude Code

Terminal
claude mcp add --transport http tells https://tells.nexugen.app/mcp

ChatGPT

  1. Open Settings, then Apps and Connectors, then Advanced, and turn on Developer mode.
  2. Choose Create, name it tells, paste the server address above and pick No authentication.
  3. 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:

claude_desktop_config.json
{
  "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.

0of 823 human texts in the held-out set got a warning or error
97.2%of plain AI text of 60 words or more flagged, same set
0.999AUC of the human-pattern score, same set
0.1%of 2,552 human texts in the locked test split got a warning or error

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.

Linted with tells
Markdown
[![Linted with tells](https://tells.nexugen.app/badge.svg)](https://tells.nexugen.app)
HTML
<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.

IdNameSeverityWhy it stands out
dashLong dashesinfoModels 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"errorThe contrast frame is the most recognised model habit there is. It invents a claim nobody made so it can knock it down.
setup-revealA drumroll before the pointwarningA drumroll before the point. People who know the point just say it.
rhetorical-qaAsking and answering yourselfwarningReal questions are asked because the writer wants to know. A question the writer answers in the next breath is a format, not a thought.
staccatoShort dramatic fragmentswarningDrama by punctuation. It reads like an ad voice-over, and models use it to fake emphasis.
triadLists of threeinfoModels default to threes because they sound complete. One real reason is usually stronger than three vague ones.
sweeping-openerA big, vague openingwarningIt delays the point and could open any post ever written. Readers skip it, and so the rest gets skipped too.
slogan-endingA slogan at the endwarningThe reader already got it. A closing slogan is the line most likely to be AI, and the easiest to cut.
sycophantic-openerPraising the questionerrorThis is the assistant voice. Nobody opens a reply to a colleague by praising the question.
chatbot-closerA chatbot sign-offwarningAn offer nobody asked for, written the same way every time. People end when they are done.
assistant-leakLeftover chatbot texterrorIt is the clearest possible tell, and it usually means a prompt or a preamble got pasted along with the answer.
ai-vocabularyWords chatbots overusewarningEach one is fine on its own. Together they are the signature of generated text, and most of them are vague.
hypeHype wordsinfoHype tells the reader how to feel instead of showing them why. It also reads as a sales voice.
intensifierWords that only add weightinfoThese words promise sincerity or weight without adding any. Models sprinkle them everywhere.
filler-transitionFiller transitionsinfoEssay glue. It announces that a point is coming instead of making it.
stock-hookA stock social media hookwarningBorrowed social-media formats. They signal that a template is running, not a person.
hedge-stackToo many hedgesinfoOne small hedge is honest. A pile of them is a model covering itself, and the sentence ends up saying nothing.
corporate-excitementAnnouncing your excitementwarningEvery launch post says it, so it says nothing. The news is the thing you shipped.
whether-youreSpeaking to everyone at oncewarningIt addresses everyone, so it speaks to no one. It is filler that models add to sound inclusive.
lecturingLecturing the readerinfoSharing what happened lets the reader draw the lesson. Telling them what to do reads as a thought-leader post.
crowd-addressTalking to a crowdinfoGood writing talks to one person. Addressing a crowd sounds like a newsletter template.
signpostingDescribing the text instead of saying itinfoIt describes the text instead of being the text.
vague-attribution"Experts say" with no sourceinfoUnsourced authority is a common model habit and a common way to make things up.
taglineA taglineinfoSlogans fail the scroll test: they could sit under any product. Specific claims do not.
explainerAn explainer under a headinginfoRead once, ignored for ever. Generated pages put one under every heading.
exclamationExclamation marksinfoOne "Congrats!" is normal. Generated copy uses them on every line to fake enthusiasm.
emojiEmoji as decorationinfoEmoji bullets are a hallmark of generated posts and READMEs.
hashtagA row of hashtagswarningA block of hashtags at the end of a post is a template habit. Generated social posts almost always add one.
semicolonSemicolons for rhythminfoIn short-form writing a semicolon usually joins two clauses for rhythm, a model habit. People write two sentences.
scare-quotesQuotes for emphasisinfoQuotes for emphasis read as sarcasm or as a model hedging a word it is not sure of.
bold-mid-sentenceBold words mid-sentenceinfoGenerated posts bold key phrases to look skimmable. In a short text it just shouts.
title-case-headingTitle Case headingsinfoGenerated documents default to Title Case. Sentence case reads like a person wrote it.
uniform-rhythmEvery sentence the same lengthinfoPeople write a long sentence, then a short one. Even rhythm across a whole passage is a strong statistical sign of generated text.
validation-openerSympathy before the answerwarningGenerated advice almost always starts with sympathy before the answer. People on forums mostly start with the answer, or with a question.
stock-warmthGreeting card linesinfoThe greeting-card lines generated messages to friends are built from. A friend writes one specific thing instead.
bold-leadBold headings on every stepwarningGenerated advice is laid out as bold-headed steps. People answering a question write paragraphs.
unfilled-placeholderA placeholder left inwarningModels 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-boilerplateForm letter lineswarningForm-letter lines. Generated emails are built almost entirely from them.
benefit-clicheStock benefit phrasesinfoStock benefit phrases. They fill the space where the real benefit should be.
so-you-can"So you can" on every featureinfoGenerated copy bolts a benefit onto every feature with the same connector.
turn-x-into-y"Turn X into Y"infoOne of the most reused headline shapes in generated marketing.
fragment-triadA slogan of three short phraseswarningA slogan built from three noun phrases. It sounds finished and says nothing a reader can check.
bold-lineBold lines used as headingsinfoChat-style output fakes headings with bold lines. In an email, post or comment it reads as generated.
summary-lineA summary at the end of every paragraphwarningModels wrap each paragraph like a school essay. People move on once the point is made.
list-everythingEverything in a listinfoBullets are the default shape of generated replies. In a message to a person, sentences carry reasons and order better.
bold-label-listBullets with bold labelswarningThis exact layout is one of the most recognisable shapes of chatbot output.
pros-consPerfectly balanced pros and consinfoBalanced halves look thorough and avoid a decision. People usually just say which one they would pick and why.
no-point-of-viewNo point of viewinfoSomeone wrote this for a reason. Text that never says who is speaking reads as generated or as a brochure.
over-qualifiedVague amountsinfoThese soften a claim until it says nothing. Models use them to stay safe.
inflated-verbInflated verbsinfoPlain verbs are what people say out loud. Inflated ones are a staple of generated and corporate prose.
generic-exampleA generic examplewarningA generic example is a placeholder for a real one. People reach for the case they actually know.
stock-courtesySupport script lineswarningScript lines from support templates. They read as no one in particular, which is the opposite of what an apology needs.
cta-endingA stock call to actioninfoGenerated 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"warningAn ad formula that guesses at the reader's problem. It reads as copy written for search engines.
label-openerA label to open withinfoFine now and then, but models open nearly every message this way.
parallel-sloganPunchy parallel lineswarningAd-copy rhythm. It sounds punchy and says nothing specific.
empty-adjectiveEmpty adjectivesinfoEvery product claims these, so they carry no information.
headings-in-messageHeadings in a short messageinfoPeople do not put section headings in an email or a chat reply. Models do it by reflex.
bold-overuseToo much boldinfoWhen everything is bold, nothing is. Generated answers bold for skimmability by default.
reassurance-frameReassurance before the answerwarningThis is how a chat assistant opens almost every how-to answer. A person who knows the answer starts with it.
listicle-introAnnouncing a listwarningThe 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-sequenceFirst, second, finallywarningA 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-closeAn upbeat moral at the endwarningThe pep talk at the end of every generated answer. It could close any answer on any subject, which is how readers spot it.