ChatKeeper

ChatKeeper is a lightweight Paper plugin for cleaner Minecraft chat. Built for servers that want chat quality controls with automatic capitalization, excessive-caps cleanup, warnings without restarting the server

Highlights

• Automatic first-letter and sentence-start capitalization for player chat messages.
• Repeated-character flood cleanup for messages like holaaaaaaaa.
• Message cooldown control for configurable message bursts.
• Anti-repeat spam blocking for consecutive similar messages like Hola, Hola, Hola.
• Excessive-caps normalization for messages that cross configurable thresholds.
• Permission-based bypass for excessive-caps correction, cooldown checks, and anti-repeat blocking.
• Case-insensitive ignore list for server-specific words like usernames, VIP, STAFF, GG, AFK, LOL, or XD.
• Optional player warnings when flood or excessive caps are corrected.
• Chat and action bar warning delivery toggles.
• Configurable staff and console notifications when players are warned.

Requirements

• Paper servers 26.1.2 or newer.
• Java 25.

Installation

1. Download the plugin jar.
2. Place the jar in your server's plugins folder.
3. Start or restart the server.
4. Edit plugins/ChatKeeper/config.yml if needed.
5. Run /chatkeeper reload after configuration changes.

Commands

Command	Permission	Description
/chatkeeper reload	chatkeeper.command.reload	Reloads the ChatKeeper configuration.
/chatkeeper status	chatkeeper.command.status	Shows enabled modules and rules.
/ck, /chatk, /kc, /keepc	chatkeeper.command	Configurable aliases for /chatkeeper.

Permissions

Permission	Default	Description
chatkeeper.command	op	Allows access to the main ChatKeeper command.
chatkeeper.command.reload	op	Allows reloading the plugin configuration.
chatkeeper.command.status	op	Allows viewing enabled modules and rules.
chatkeeper.notify	op	Receives warning notifications for staff.
chatkeeper.bypass.excessive-caps	false	Bypasses excessive-caps correction and warnings.
chatkeeper.bypass.cooldown	false	Bypasses message cooldown checks and warnings.
chatkeeper.bypass.anti-repeat	false	Bypasses anti-repeat spam blocking and warnings.

Configuration

# Controls correction warnings for all chat modules.
warnings:
  # Sends a warning to the player when their message is corrected.
  enabled: true

  # Sends the warning as a normal chat message.
  chat: true

  # Sends the warning above the hotbar.
  actionbar: true

  # Notifies staff and/or console when a player is warned.
  notify:
    # Sends the warning reason to online staff with this permission.
    staff: true
    staff-permission: chatkeeper.notify

    # Sends the warning reason to the server console.
    console: true

# Controls in which worlds all chat modules can run.
worlds:
  # Enables or disables global world filtering.
  enabled: true

  # whitelist applies modules only in these worlds.
  # blacklist applies modules everywhere except these worlds.
  mode: whitelist # whitelist, blacklist

  # Use ALL to target every world at once.
  # In whitelist mode, ALL allows modules in every world.
  # In blacklist mode, ALL disables modules in every world.
  worlds:
    - ALL
    # - spawn
    # - lobby
    # - survival
    # - world

# Controls repeated character flood cleanup in chat messages.
flood:
  # Enables or disables repeated character correction.
  enabled: true

  # Action used when repeated character flood is detected.
  # warn-only corrects and warns. block cancels the message and warns.
  action: warn-only # block, warn-only

  # Amount of consecutive equal letters, numbers, or symbols required before correction.
  minimum-repetitions: 6

  # Amount of repeated characters left after correction.
  # Example: "helloooooooo" becomes "hello" with the default value.
  replacement-repetitions: 1

# Controls how many chat messages a player can send in a short time.
cooldown:
  # Enables or disables message cooldown checks.
  enabled: true

  # Action used when the message limit is exceeded.
  # block cancels the message and warns. warn-only only warns.
  action: block # block, warn-only

  # Players with this permission skip cooldown checks and warnings.
  bypass-permission: chatkeeper.bypass.cooldown

  # Maximum amount of messages allowed inside the time window.
  # With the default value, the sixth message in 5 seconds is blocked.
  max-messages: 5

  # Time window, in seconds, used to count messages.
  time-window-seconds: 5

# Controls consecutive repeated-message spam.
anti-repeat:
  # Enables or disables repeated-message blocking.
  enabled: true

  # Action used when repeated-message spam is detected.
  # block cancels the message and warns. warn-only only warns.
  action: block # block, warn-only

  # Players with this permission skip anti-repeat blocking and warnings.
  bypass-permission: chatkeeper.bypass.anti-repeat

  # Skips anti-repeat checks for messages whose first visible character is !, #, @, or /.
  ignore-prefixed-messages:
    enabled: true

  # Maximum amount of consecutive similar messages allowed inside the time window.
  # With the default value, the fifth similar message is blocked.
  max-repeated-messages: 4

  # Time window, in seconds, used to count consecutive similar messages.
  time-window-seconds: 15

  # Minimum similarity percentage required to consider two messages repeated.
  minimum-similarity-percentage: 85

  # Minimum normalized message length required before anti-repeat is checked.
  minimum-message-length: 8

# Controls automatic chat capitalization corrections.
capitalization:
  # Enables or disables every capitalization feature below.
  enabled: true

  # Words ignored by first-letter and excessive-caps corrections.
  # Matching is case-insensitive. Online player usernames are ignored automatically.
  ignored-words:
    - VIP
    - STAFF
    - GG
    - AFK
    - LOL
    - XD

  # Skips first-letter and excessive-caps corrections for messages whose first visible
  # character is !, #, @, or /. Flood correction still applies to those messages.
  ignore-prefixed-messages:
    enabled: true

  # Capitalizes the first visible letter of each message and after ., ?, or !.
  first-letter:
    enabled: true

  # Normalizes messages that contain too many uppercase letters.
  excessive-caps:
    enabled: true

    # Action used when excessive caps are detected.
    # warn-only corrects and warns. block cancels the message and warns.
    action: warn-only # block, warn-only

    # Players with this permission skip excessive-caps correction and warnings.
    bypass-permission: chatkeeper.bypass.excessive-caps

    # Minimum amount of letters required before checking for excessive caps.
    minimum-letters: 12

    # Percentage of uppercase letters required to trigger the correction.
    uppercase-percentage: 70

# Controls command aliases for /chatkeeper.
command:
  # Short command names registered by ChatKeeper.
  # If another plugin already uses one of these aliases, ChatKeeper will keep
  # working through /chatkeeper and will warn about the conflicting alias.
  aliases:
    - ck
    - chatk
    - kc
    - keepc

Command alias conflicts

Short aliases are shared by every plugin on the server. If another plugin already owns /ck, ChatKeeper will warn at startup and /chatkeeper will remain available.

Admins who want to force /ck to ChatKeeper can add this to the server's commands.yml:

aliases:
  ck:
    - 'chatkeeper:chatkeeper $1-'

Support

Open an issue on GitHub with:

• Your server software and version.
• Your Java version.
• The ChatKeeper version.
• Relevant console logs or configuration snippets.

License

ChatKeeper is licensed under the MIT License. Commercial use, modification, distribution, and private use are allowed under the license terms. See LICENSE for details.