Plainspeak

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

Website · GitHub · npm

---

You know the voice. It is a bit too clean. 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 puts a plain human voice inside your agent.

The point is simple. Agents make easy things sound hard. They reach for big words, long phrases, and heavy writing when a short one would do. Plainspeak turns that off. What should be simple stays simple.

Before / after

Your agent explains a fix:

Let me walk you through a robust, comprehensive solution that leverages cutting-edge technology to seamlessly streamline your workflow. It is important to note that this utilizes a nuanced approach to error handling.

With plainspeak:

Here is a simple way to save time. The system handles errors in a few steps.

More rewrites in rules/voice.md.

How it works

Plainspeak is one short set of voice rules. The agent keeps them in its context on every reply. You never have to ask for them.

The rules do three things:

1. Ban a word list. Words like delve, leverage, robust, seamless, and utilize are never written.
2. Ban filler phrases. No "Let's dive in", no "It's important to note", no "I hope this helps".
3. Ban em dashes. Split the sentence with a period or a comma. Or write two sentences.

They also ask for plain words, short sentences, and a direct tone. Say what you mean first. Do not hedge. Do not over-apologize. Match the reader's tone.

The full list is in rules/voice.md. That file is the single source of truth. Every adapter reads it or copies it, so all agents follow the same rules.

Install

The Claude Code, Codex, and Copilot plugins run two tiny Node.js lifecycle hooks. node needs to be on your PATH.

Claude Code

/plugin marketplace add CoderSufiyan/plainspeak
/plugin install plainspeak@plainspeak

Send those as two separate prompts. The plugin adds the voice rules on every session start and into every subagent.

Codex

codex plugin marketplace add CoderSufiyan/plainspeak
codex plugin add plainspeak@plainspeak

Run codex, open /hooks, review and trust the two hooks, then start a new thread.

GitHub Copilot CLI

copilot plugin marketplace add CoderSufiyan/plainspeak
copilot plugin install plainspeak@plainspeak

OpenCode

Install the package, then add it to your opencode.json:

{ "plugin": ["plainspeak"] }

From a checkout instead, point it at the local plugin:

{ "plugin": ["./.opencode/plugins/plainspeak.mjs"] }

The plugin appends the voice rules to the system prompt on every turn. OpenCode also auto-loads this repo's AGENTS.md, so the rules hold even without the plugin.

Cursor, Windsurf, Cline, Copilot Chat, and any agent

These read rule files from your project. The CLI writes them for you:

npx plainspeak install

It creates:

• AGENTS.md for Codex and generic agents
• .cursor/rules/plainspeak.mdc for Cursor
• .windsurf/rules/plainspeak.md for Windsurf
• .clinerules/plainspeak.md for Cline
• .github/copilot-instructions.md for GitHub Copilot Chat
• .agents/rules/plainspeak.md for the agents standard

Existing AGENTS.md files stay intact. The rules go in a marked block at the end.

CLI

plainspeak install [dir]    Inject voice rules into a project (default: cwd)
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

check does the enforcing. Point it at a draft, a changelog, or an agent transcript and it reports every banned word and every em or en dash:

plainspeak check draft.md
#   banned: "leverage" x1
#   em dash x2

It exits with a non-zero code when anything is found, so it can gate CI.

Turn it off

Say stop plain voice in a session to turn it off, and start plain voice to turn it back on.

Uninstall

Host	Command
Claude Code	/plugin remove plainspeak
Codex	codex plugin remove plainspeak
Copilot CLI	copilot plugin remove plainspeak
OpenCode	Remove plainspeak from opencode.json
Cursor / Windsurf / Cline / etc.	npx plainspeak uninstall

Development

Edit rules/voice.md first, then regenerate the agent copies:

npm run build
npm run check
npm test

build writes the rule files from rules/voice.md. check fails if any of them drift. The test suite covers the rule copies, the voice rule content, the CLI, and the lint check.

FAQ

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 fancier word? Use it. The rules are a default, not a cage. Say stop plain voice to turn it off.

Why "plainspeak"? Plain speaking is the point.

License

MIT.