queensguard

An MCP server that acts as a silent English coach inside your AI assistant. It intercepts every conversation, either silently rewrites your message in clean English (example mode) or surfaces past mistake patterns and delivers one targeted improvement tip (teach mode), building a persistent history of your recurring errors so you stop making the same mistake twice.

How it works

queensguard runs in one of two modes (default: example):

Example mode — silent rewrite, no coaching:

User message
     │
     ▼
Hook emits instruction: silently rewrite in clean English
     │
     ▼
Agent prepends the rewrite to its response

Teach mode — tip-based coaching:

User message
     │
     ▼
analyze-english ──► match against stored mistake history + exclusions
     │
     ▼
Agent generates one targeted tip (skips categories matching exclusions)
     │
     ▼
log-tip ──► persists new mistake to ~/.queensguard/tips.json
     │
     ▼
Agent prepends tip to response

queensguard is ON by default in example mode — no setup needed after install. The queensguard-check hook fires before every tool call via bin/queensguard-hook.js. Use queensguard-off to silence it explicitly.

Tools

analyze-english

Reads ~/.queensguard/tips.json and returns stored mistake entries whose category matches patterns detected in the given text.

| Input | Type | Description | |---|---|---| | text | string | The user's raw message |

Returns: { past_mistakes: TipEntry[], exclusions: string[], text: string }

log-tip

Appends a newly detected mistake to the tip store. Writes atomically (temp file → rename).

| Input | Type | Description | |---|---|---| | category | string | Kebab-case label — e.g. article-usage, tense-consistency, word-choice | | description | string | Plain-English explanation of the mistake and the correct form | | example | string | The original text excerpt that triggered the tip |

Returns: { saved: true, category, total_for_category: number }

set-queensguard-mode

Enables or disables the coach and optionally sets the active mode. Both parameters are optional — omit either to preserve the current value. State persists to ~/.queensguard/state.json.

| Input | Type | Description | |---|---|---| | enabled | boolean (optional) | true to activate, false to pause | | mode | string (optional) | "example" (silent rewrite, default) or "teach" (tip-based coaching) |

Returns: { queensguard_enabled: boolean, queensguard_mode: string }

add-exclusion

Appends a natural-language rule to the exclusion list. The agent interprets these rules when deciding whether to surface a tip — e.g. "I don't capitalize intentionally" or "ignore word-choice suggestions". Rules are returned by analyze-english alongside past_mistakes.

| Input | Type | Description | |---|---|---| | rule | string | Natural-language description of what to exclude |

Returns: { saved: true, total_exclusions: number }

Prompts

| Prompt | Effect | |---|---| | queensguard-on | Calls set-queensguard-mode(true) and confirms activation | | queensguard-off | Calls set-queensguard-mode(false) and confirms deactivation |

Hook: queensguard-check

• Trigger: PreToolUse — fires before every tool call
• Behavior: Reads ~/.queensguard/state.json. If queensguard is ON, emits a mode-specific instruction: in example mode, asks for a silent rewrite; in teach mode, instructs the agent to call analyze-english, respect exclusions, generate a tip, call log-tip, and prepend the tip.
• Implementation: bin/queensguard-hook.js (extracted from inline script for maintainability).
• Effect: Zero overhead when OFF. No API calls — pure shell.

Data

All state lives in ~/.queensguard/:

~/.queensguard/
├── tips.json          # array of logged mistake entries
├── exclusions.json    # array of natural-language exclusion rules
└── state.json         # { enabled: boolean, mode: string, updated_at: ISO }

tips.json entry shape:

{
  "id": "uuid-v4",
  "category": "article-usage",
  "description": "Use 'an' before vowel sounds, not 'a'. 'a apple' → 'an apple'.",
  "example": "I ate a apple.",
  "timestamp": "2026-06-03T10:00:00.000Z"
}

Install

npm install -g queensguard
queensguard init

init starts the MCP server silently in the background. queensguard is ON by default — no further setup needed.

To toggle or configure the coach inside your AI session:

/queensguard-on
/queensguard-off

Or call the tool directly:

set-queensguard-mode { enabled: true }
set-queensguard-mode { mode: "teach" }
set-queensguard-mode { mode: "example" }

To add an exclusion rule:

add-exclusion { rule: "I don't capitalize intentionally" }

Mistake categories

Built-in pattern detection covers:

| Category | Detects | |---|---| | article-usage | Wrong or missing a/an/the | | subject-verb-agreement | He/she/it with plural verb forms | | tense-consistency | Mixed past and present tense | | preposition | Wrong preposition for common adjectives and verbs | | word-choice | Vague or informal word selection | | capitalization | Lowercase sentence starts, proper nouns |

Custom categories are stored automatically as new mistakes are logged — the store grows with you.

Architecture note

queensguard is a pill — an MCP server consumed by the AI, not calling it. All pattern detection is deterministic. The AI is the intelligence layer that synthesises the structured output into natural-language tips.