Peripheral

Peripheral

Script Minecraft with Python.

Write .py scripts that read live game data, control your player, build custom GUIs, and render always-on HUD overlays — all without touching Java. Drop a script in a folder, hit run, and watch it go.

What it does

Peripheral runs a lightweight HTTP server inside Minecraft (localhost:25585) and injects a helper module called mc into every script. Scripts run in the background as you play — reading your health, sending chat messages, drawing on your screen, or moving with scripts.

No extra dependencies. No config files to hand-edit. Everything is managed through a clean in-game GUI (press G).

Features

Python scripting

• Scripts live in config/peripheral/scripts/ — edit them in any text editor or in-game
• The mc module is injected automatically. Just from mc import * and go.
• Scripts run in the background — start several at once, stop them independently

AI script builder

Open the Build tab, type a script name, describe what you want, and the AI writes it directly to the file. Uses your own Claude or OpenAI API key. Chat history is saved so you can pick up where you left off, fix errors by sending logs back to the AI, and manage multiple scripts from the sessions menu.

Player control

say() · look() · use_item() · equip() · jump() · sprint() · sneak() · move() · click_block() · attack() · drop_item()

Game data

state() · pos() · health() · inventory() · chat_log()

HUD overlays

Render persistent elements directly on the game screen while you play:

• Labels — text with color and shadow
• Bars — progress bars (health, durability, XP, anything)
• Rects — background panels with optional border
• Item sprites — render any Minecraft item icon by ID
• Anchored to any screen corner or center — positions scale with resolution

Custom in-game screens

open_gui() builds real Minecraft screens from Python — buttons, text fields, labels, sliders, checkboxes. Press H in-game to show/hide. Scripts keep data live while the screen is open.

`

Navigation

goto(x, z) · nav_status()

HTTP API

Every endpoint the mc module uses is also available externally on localhost:25585. Wire up a browser dashboard or a local tool — all without touching the game.

Included example scripts

| Script | What it does |
|—|—|
| hello_world.py | Shows position, health, nearby entities — verify everything works |
| armor_hud.py | Vertical item-icon + durability HUD on the right side of the screen |
| auto_eat.py | Automatically eats food when hunger drops |
| auto_mine.py | Scripts the player to mine a target ore automatically |
| welcome_bot.py | Greets players when they join |
| follow_on_command.py | Follows a player when they say “follow me” in chat |
| custom_gui.py | Full interactive GUI example — buttons, inputs, live updates |
| api_server.py | Starts a local HTTP server so external apps can read game state |
| openai_chat.py | Players whisper questions to a configured AI API, it answers in chat |
| server_status.py | Pings Minecraft servers and shows player counts and MOTD |
| weather_display.py | Fetches real-world weather and displays it in-game |
| web_dashboard.py | Browser dashboard — view game state from any tab on your local network |
| clickable_links.py | Shows how to send rich messages with clickable URLs and hover text |

Still in development

This mod is actively being worked on. If you run into any bugs, issues, or have suggestions, please open an issue at github.com/Sl0oth/peripheral/issues.

Getting started

1. Install the mod (Fabric, 1.21.11 – 26.1)
2. Launch Minecraft — example scripts and PERIPHERAL_API.md are written to config/peripheral/scripts/ automatically
3. Press G to open the Peripheral panel
4. Hit Run next to any example script
5. To build your own with AI: open the Build tab, type a script name, and start chatting

External connections

Peripheral’s HTTP server only listens on localhost and never connects to any remote server on its own. The Build tab sends messages to the Anthropic or OpenAI API using your own key — nothing is sent without you initiating it. Some example scripts make outbound HTTP requests to third-party APIs; this only happens when you explicitly run them, and the endpoints are clearly visible in the script source.

Multiplayer

Peripheral gives you tools that can automate player actions. It is your responsibility to ensure any scripts you run comply with the rules of the server you are playing on. Many servers prohibit automation mods. When in doubt, check with the server owner before running automation scripts in multiplayer.

Requirements

• Minecraft 1.21.11 – 26.1
• Fabric Loader 0.18.4+
• Fabric API

Client-side only

Peripheral runs entirely on the client. No server installation needed. Works on singleplayer, multiplayer, and Realms.

Disclaimer

This mod is provided as-is with no warranty. The author is not liable for loss of items or game progress, save file corruption, server bans, damages caused by scripts you write or run, or any consequences from connecting the mod to external services. You are solely responsible for any scripts you create or execute. Use of this mod on multiplayer servers is at your own risk — always check server rules first. Full terms at github.com/Sl0oth/peripheral.

100% of the mod code was written by Claude Code (Anthropic’s AI coding assistant), directed by Sl0oth.