JustAFK

JustAFK is a lightweight, server-side AFK plugin for Minecraft 26.2 servers.

It automatically detects inactive players, provides manual and administrative AFK controls, announces AFK state changes, and can display the current AFK duration directly in the TAB player list.

JustAFK focuses on being simple, configurable, and easy to run. It does not use NMS, databases, or external runtime libraries.

JustAFK is completely server-side. Players do not need to install anything on their clients.

Why use JustAFK?

Lightweight automatic AFK detection
Sensible configuration defaults
Manual AFK command for every player
Administrative control over other online players
Configurable AFK announcements
Optional TAB player-list prefix
AFK duration shown in minutes or hours
Immediate configuration saving through commands
Folia-aware scheduling
No NMS or external runtime dependencies
Compatible with permission managers such as LuckPerms

JustAFK only marks players as AFK. It does not kick, freeze, teleport, punish, or restrict them.

Preview

Player list	Chat announcements

How AFK detection works

By default, a player is marked as AFK after 300 seconds, or five minutes, without changing position.

JustAFK compares the player's world and exact X, Y, and Z coordinates:

Looking around does not reset the inactivity timer
Changing yaw or pitch does not count as movement
Any positional or world change counts as activity
Positional movement immediately removes the AFK state
Manually turning AFK off starts a fresh inactivity period
Reconnecting starts a new session and resets the AFK state

Automatic detection runs once per second, keeping the timer responsive without checking every server tick.

AFK duration

The optional TAB prefix displays how long the player has been marked as AFK.

Examples:

A newly AFK player displays 0m
Five minutes displays 5m
Fifty-nine minutes displays 59m
One hour displays 1h
Two hours displays 2h

Minutes are shown below 60 minutes. From 60 minutes onwards, the duration is shown in whole hours.

The default format is:

&7[AFK {duration}]&r

This produces a grey prefix before the player's existing player-list name.

Commands

Command	Default access	Permission	Description
`/afk`	All players	`justafk.use`	Toggle your own AFK state.
`/afk <player>`	Operators	`justafk.use` and `justafk.others`	Toggle an online player's AFK state.
`/afk <player> on`	Operators	`justafk.use` and `justafk.others`	Mark an online player as AFK.
`/afk <player> off`	Operators	`justafk.use` and `justafk.others`	Remove an online player's AFK state.
`/afk <player> toggle`	Operators	`justafk.use` and `justafk.others`	Toggle an online player's AFK state explicitly.
`/justafk`	Operators	`justafk.config`	Show the command help.
`/justafk help`	Operators	`justafk.config`	Show the command help.
`/justafk status`	Operators	`justafk.config`	Display the active configuration.
`/justafk reload`	Operators	`justafk.config`	Reload `config.yml`.
`/justafk set timeout <seconds>`	Operators	`justafk.config`	Change the automatic AFK timeout.
`/justafk set announcements <all\\|ops\\|none>`	Operators	`justafk.config`	Change the announcement audience.
`/justafk set playerlist <on\\|off>`	Operators	`justafk.config`	Enable or disable the TAB prefix.

The /jafk alias can be used instead of /justafk.

Running /afk <player> without on, off, or toggle defaults to toggle.

The target player must be online. Player names are matched exactly without case sensitivity.

Permissions

Permission	Default	Description
`justafk.use`	Everyone	Allows players to use `/afk` on themselves.
`justafk.others`	Operators	Allows changing another online player's AFK state.
`justafk.config`	Operators	Allows access to all `/justafk` administrative commands.
`justafk.admin`	Operators	Grants all JustAFK permissions.

justafk.admin includes:

justafk.use
justafk.others
justafk.config

Because the root /afk command requires justafk.use, a moderator who should manage other players needs both justafk.use and justafk.others.

LuckPerms examples

LuckPerms is optional. JustAFK uses the standard Bukkit permission system and works with permission plugins that manage Bukkit permissions.

Allow the default group to toggle its own AFK state:

/lp group default permission set justafk.use true

Allow a moderator group to manage other players:

/lp group moderator permission set justafk.use true
/lp group moderator permission set justafk.others true

Give an administrator group every JustAFK permission:

/lp group admin permission set justafk.admin true

Allow a staff group to manage the configuration without granting every permission:

/lp group staff permission set justafk.config true

Remove self-service AFK access from the default group:

/lp group default permission set justafk.use false

Replace default, moderator, admin, or staff with the names of the groups used by your server.

The ops announcement audience refers to players who are actual Minecraft server operators. It does not include players merely because they have justafk.admin through LuckPerms.

Configuration

The default config.yml is:

# Time without a position change before a player is marked as AFK.
# The default is 300 seconds (5 minutes).
inactivity-timeout-seconds: 300

announcements:
  # Available values: all, ops, none
  audience: all

player-list:
  # Adds a grey AFK duration before the player's existing tab-list name.
  enabled: true
  format: "&7[AFK {duration}]&r "

messages:
  # Legacy colour codes using '&' are supported.
  command-prefix: "&8[&7JustAFK&8]&r "
  became-afk: "&8[&7JustAFK&8]&r &7{player} is now AFK."
  became-active: "&8[&7JustAFK&8]&r &7{player} is no longer AFK."

Configuration options

Option	Default	Accepted values	Description
`inactivity-timeout-seconds`	`300`	A whole number of at least `1`	Time without movement before automatic AFK.
`announcements.audience`	`all`	`all`, `ops`, `none`	Controls who receives entry and exit announcements.
`player-list.enabled`	`true`	`true` or `false`	Enables the TAB player-list prefix.
`player-list.format`	`&7[AFK {duration}]&r`	Text containing `{duration}`	Controls the prefix displayed before the existing player-list name.
`messages.command-prefix`	JustAFK prefix	Any text	Prefix used for command responses.
`messages.became-afk`	Default AFK message	Any text	Message sent when a player enters AFK.
`messages.became-active`	Default active message	Any text	Message sent when a player leaves AFK.

Announcement audiences

all — sends announcements to every online player
ops — sends announcements only to online server operators
none — disables AFK announcements

The same audience is used for both entering and leaving AFK.

Placeholders

{duration} is required in player-list.format
{player} can be used in the AFK entry and exit messages

Legacy colour codes using & are supported.

Configuration commands save their changes to config.yml immediately.

When editing config.yml manually, run:

/justafk reload

Compatibility

Platform	Support
Paper 26.2	Primary and recommended platform
Purpur 26.2	Supported as a Paper fork
Folia 26.2	Folia-aware scheduler integration included
Spigot 26.2	Best-effort Bukkit API compatibility
CraftBukkit 26.2	Best-effort compatibility
Sponge	Not supported

Paper is the primary development target and receives the strongest compatibility focus.

Folia uses its global and entity schedulers. Paper remains the most extensively tested platform, so platform-specific issues should be reported.

Spigot and CraftBukkit compatibility is provided on a best-effort basis. The plugin is compiled against the Paper API, but it avoids NMS and direct Paper-only class dependencies in its normal Bukkit code.

Sponge uses a different plugin API and lifecycle and would require a separate implementation.

Requirements

Minecraft Java Edition 26.2
Java 25
A compatible server platform

No client mod is required.

No runtime dependencies are required. LuckPerms is supported through standard Bukkit permissions but is not required.

Installation

Download the latest JustAFK JAR from Modrinth.
Place the JAR inside the server's plugins directory.
Start or restart the server.
Open plugins/JustAFK/config.yml to review the configuration.
Run /justafk reload after making manual configuration changes.
Configure additional permissions with LuckPerms if needed.

Frequently asked questions

Does JustAFK kick inactive players?

No. JustAFK only marks players as AFK, announces state changes, and optionally displays a TAB prefix.

Do players need to install anything?

No. JustAFK is completely server-side.

Does looking around reset the timer?

No. Only a change in world position resets the inactivity timer.

Does the AFK state persist after reconnecting?

No. AFK states are session-based and reset when a player disconnects.

Can announcements be disabled?

Yes. Set announcements.audience to none or run:

/justafk set announcements none

Can the TAB prefix be disabled?

Yes. Run:

/justafk set playerlist off

Can messages and colours be customized?

Yes. Edit the message and player-list settings in config.yml. Legacy & colour codes are supported.

Source and support

JustAFK is open source and licensed under the MIT License.

JustAFK Plugin