Moderating Private Messages with SocialSpy and CmdSpy

Use SocialSpy to monitor private conversations and CmdSpy to track player commands. Covers spy formats, sensitive masking, and persistent state.

PumpkinMsg gives your moderation team two complementary surveillance tools: SocialSpy for private conversations and CmdSpy for player commands. Both tools are non-intrusive to normal players, persist across server restarts, and respect your configured format strings so spy output always matches your server’s visual style.

SocialSpy

SocialSpy lets authorized staff members receive a copy of every private message exchanged on the network. Staff use /socialspy (alias /spy) to toggle the feature on or off. The permission required is pumpkinmsg.staff.spy.

Global Mode vs. Player-Specific Mode

Global Mode

Running /socialspy with no argument toggles global mode. In global mode you receive a copy of every private message sent anywhere on the network.

/socialspy        # enable global spy
/socialspy        # run again to disable

When enabled you receive the confirmation:

[Staff Spy] » Global mode enabled.

Player-Specific Mode

Running /socialspy <player> pins the feed to a single player. You only receive messages where that player appears as the sender or the recipient — all other conversations are invisible to you.

/socialspy Steve    # watch only Steve's conversations
/spy Alex           # alias form

When enabled you receive:

[Staff Spy] » Watching: Steve.

To stop watching a specific player, run /socialspy with no argument to disable spy entirely, then run /socialspy again with no argument to re-enable it in global mode.

What Staff See

Each intercepted message is formatted using the spy string from config.toml:

spy = "<#C678DD>[Spy] <sender_prefix><#61AFEF><sender> <#5C6370>-> <target_prefix><#61AFEF><target><#5C6370>: <#D19A66><message>"

The <sender_prefix> and <target_prefix> tokens are resolved via LuckPerms, so moderators can immediately identify the ranks of both participants. If LuckPerms is not installed, those tokens resolve to an empty string.

Both the sender and the recipient of a message are automatically excluded from the spy broadcast for that message — they already see their own conversation and do not receive a duplicate spy line.

CmdSpy

CmdSpy gives staff visibility into the commands players execute. The permission required is pumpkinmsg.staff.cmdspy. Use /spycommands (alias /cmdspy) to manage it.

Scope Options

Paper (Single Server)

On a Paper server, /spycommands is a simple toggle. Running it once enables command monitoring for all players on that server. Running it again disables it.

/spycommands    # toggle on/off

Velocity (Proxy)

On Velocity you have granular control over which backend server to monitor.

/spycommands              # toggle global cmdspy
/spycommands global       # explicitly watch all servers
/spycommands survival     # watch only the "survival" server
/spycommands off          # disable cmdspy entirely

The <server> token in the cmdspy format string shows which server the command originated from, making it easy to filter your logs after the fact.

Sensitive Command Masking

PumpkinMsg automatically masks commands that could expose player credentials. The following commands are never shown in CmdSpy output, regardless of who is watching:

• /login
• /register
• /changepassword

This masking is enforced at the plugin level and cannot be disabled through configuration. It protects player account security no matter how staff configure their spy settings.

CmdSpy Format

The output uses the cmdspy string from config.toml:

cmdspy = "<#C678DD>[Cmd Spy] <player_prefix><#61AFEF><player> <#5C6370>used <white>/<command> <#5C6370>on <#E5C07B><server>"

Message Delivery Flow

Understanding the order in which PumpkinMsg evaluates each condition helps you predict exactly what players and staff will see when a message is sent.

1. Check sender togglemsg

   If the sender has run /togglemsg to disable their own outgoing messages, the plugin sends them sender-toggled-off and stops.

2. Check target is online

   If the target player is offline or not found on the network, the plugin sends the sender player-offline and stops.

3. Check self-message

   If the sender is targeting themselves, the plugin sends cannot-msg-self and stops.

4. Check target togglemsg (bypass)

   If the target has disabled incoming messages via /togglemsg, the plugin sends target-toggled-off to the sender — unless the sender holds pumpkinmsg.staff.bypass, in which case delivery continues.

5. Check ignore list (bypass)

   If the target has ignored the sender, the plugin sends player-ignoring-you — unless the sender holds pumpkinmsg.staff.bypass, in which case delivery continues.

6. Deliver message

   The plugin formats and sends the sender string to the sender and the receiver string to the target, then records both players as each other’s last-message partner for /reply.

7. Broadcast to spies

   The plugin iterates over all online players who have SocialSpy active. Each spy receives the spy format string — unless they are the sender or the recipient of the message. If a spy has pinned their feed to a specific player, they only receive the broadcast if that player is involved in the current message.

Persistent State

All spy, ignore, and togglemsg state is written to flat files in the plugins/PumpkinMsg/ data folder whenever it changes. This means:

• A staff member’s SocialSpy or CmdSpy session survives proxy/server restarts.
• A player’s ignore list and togglemsg preference are restored automatically when they reconnect.

No manual backup of a database is needed — the flat files in the data folder are the entire state of the plugin.