sufiyan.cc

plainspeak

A Voice layer for AI agents to write like a human.

You know the voice. Every reply opens with "Certainly!" or "Let's dive in". Em dashes land in every other line. It says "leverage", "robust", and "seamless" so much you can tell a machine wrote it from across the room.

Plainspeak is a voice layer for AI agents. One small set of rules goes into the agent's context and stays there. What should be simple stays simple.

01 / Before / after

Same task. One reads human.

Real outputs from the same agent. Left is without plainspeak. Right is with it.

Without plainspeak · Debug a slow page

I'd approach this systematically — first ruling out the user, then checking the server side, then the network, then the page itself:

With plainspeak · Debug a slow page

I'd start with where the problem actually lives, then narrow it down.

Without plainspeak · Email a landlord

The tap in the kitchen/bathroom has a leak that's getting worse — it drips constantly and is starting to waste water. Could you arrange for it to be repaired?

With plainspeak · Email a landlord

The tap in the kitchen is leaking. Could you send someone to fix it? Let me know what day works. Thanks!

Without plainspeak · Say thanks

Thank you for renewing your subscription with us — we truly appreciate your continued trust in Company.

With plainspeak · Say thanks

Thanks for renewing your subscription. It means a lot to us that you're sticking with us.

Without plainspeak · Explain an API

An API (Application Programming Interface) is like a menu at a restaurant. You're the customer and the kitchen is the software — the menu lists the dishes you can order.

With plainspeak · Explain an API

An API is a waiter at a restaurant. You don't go into the kitchen to get your food. You tell the waiter what you want, and they bring it back.

Without plainspeak · Out sick tomorrow

Hey all — just letting you know I'll be out sick tomorrow. I'll be offline but will catch up when I'm back. If anything urgent comes up, Name can help in the meantime.

With plainspeak · Out sick tomorrow

Hi team, I'm not feeling well and will be out tomorrow. I'll be back Monday. For anything urgent, ping Sam and she'll handle it.

Without plainspeak · Follow up after an interview

Hi Name, I hope you're doing well. I'm writing to follow up on my interview for the Role position. I really enjoyed our conversation and learning more about the team, and I remain very interested in the role.

With plainspeak · Follow up after an interview

Hi Name, I wanted to check in on the role I interviewed for last week. I really enjoyed our talk. I'm still very interested in the job. Any news on the timeline?

02 / Use cases

Where it helps

Commit messages and PR descriptions

Short, plain, and honest. No "This PR enhances the user experience".

Emails and customer replies

Draft messages that sound like a person, not a template.

Docs and changelogs

Pages people can read without a thesaurus.

Product chat

If your product has an AI agent, keep its voice plain and friendly.

Code comments

Comments that say why, in plain words.

Tweets and posts

Draft posts that do not read like a bot.

03 / How it works

One rule set, every agent

One rules file is the source of truth. It bans about 60 words, 40 phrases, and every em dash. It also asks for plain words, short sentences, and a direct tone.

The rules go into the agent's always-on context. That is the whole trick. No plugin magic, no waiting for you to ask.

$

Claude Code and Codex get the rules through lifecycle hooks on session start.

$

opencode gets them through a plugin that appends to the system prompt.

$

Cursor, Windsurf, Cline, and Copilot get them as rule files, written by the CLI.

04 / The rules

What the agent must follow

01

Ban the AI words. delve, leverage, robust, seamless, utilize, and 50 more.

02

Ban the filler phrases. Let's dive in, it's important to note, I hope this helps.

03

Ban em dashes. Split the sentence with a period or a comma.

04

Use plain words and short sentences.

05

Use the small words humans say: also, to be honest, actually, by the way.

06

Be direct. No hedging, no padding, no over-apologizing.

05 / Supported agents

Seven agents, one voice

Claude Code, Codex, opencode, Cursor, Windsurf, Cline, and GitHub Copilot. The same rules, wherever your agent lives.

06 / Install

One line to get started

npm

npm i plainspeak

opencode

{ "plugin": ["plainspeak"] }

claude code

/plugin install plainspeak@plainspeak

codex

codex plugin add plainspeak@plainspeak

07 / CLI

Install, check, enforce

plainspeak install [dir]Inject voice rules into a project
plainspeak uninstall [dir]Remove injected voice rules
plainspeak status [dir]Show what is installed where
plainspeak check <file>Lint a file for banned words and dashes

08 / FAQ

Questions

Does it change what the agent builds?

No. Only how it writes. Code stays the same.

Does it need a config file?

No.

What if I want a fancy word?

Use it. The rules are a default, not a cage. Say "stop plain voice" to turn it off.

Is it free?

Yes. MIT and zero dependencies.