CookieOS is a Lua-based operating system overlay for CC:Tweaked (ComputerCraft) computers in Minecraft. It replaces the default shell experience with a graphical start menu, a suite of built-in programs, and a globally available utility library calledDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/PrinceOfCookies/CookieOS/llms.txt
Use this file to discover all available pages before exploring further.
cosUtils. Rather than simply dropping you into a plain terminal prompt, CookieOS boots through a structured loading sequence that sets up the environment, registers shell enhancements, launches background event handlers, and then presents an interactive menu — all before you type a single command. The current release is CookieOS v2.2.5.
Key Features
Graphical Start Menu
A centered, keyboard-driven menu replaces the raw shell prompt. Navigate with the Up/Down arrow keys, press Enter to select, and return to it at any time. The menu bar always displays the current OS version and a live clock.
File Explorer
A two-panel graphical file browser built into the Programs submenu. Browse directories, inspect file size, last-modified time, created date, and read-only status — all without leaving the GUI.
Music Player
Play audio discs through a connected speaker peripheral directly from the Programs menu. The option is automatically greyed out when no speaker is detected.
AI Chat (Gemini)
A built-in chat program powered by the Google Gemini API. The AI assistant is named Davey and is pre-instructed with knowledge of modded Minecraft mods including Create, Mekanism, Mystical Agriculture, and more. Requires a configured API key and a chatBox peripheral.
Player Tracker
Track nearby players using a connected
playerDetector peripheral combined with a monitor and chatBox. The option is greyed out automatically when any required peripheral is missing.Enhanced Shell Commands
CookieOS overrides
shell.resolveProgram to check /programReplacements/ first, giving you improved versions of list, ls, reboot, shutdown, about, and screenfetch. The os.reboot and os.shutdown functions are wrapped to show a “Goodbye” screen before acting.cosUtils API
A global Lua library automatically loaded at boot from
apis/cUtils.lua. It provides utilities for time formatting, file operations, screen management, loading bars, BSOD error screens, data compression, RC4 encryption, MD5 hashing, and more — available in every script you write.screenfetch
Run
screenfetch in the command prompt for a CC:Tweaked-style system information readout: OS version, computer type, uptime, total storage size, Lua version, host string, and the number of cosUtils functions currently loaded.CookieOS is primarily built for personal use by its author. It works on any CC:Tweaked computer, but an Advanced Computer is strongly recommended for full colour support. If you want to contribute a fix or a new feature, pull requests are welcome on the GitHub repository. Bug reports can be filed in the Issues tab.
Boot Sequence
When a CC:Tweaked computer running CookieOS powers on, the startup folder is executed automatically by the ComputerCraft runtime. CookieOS uses four sequential files to go from a blank screen to an interactive menu:1. startup/loading.lua
This is the entry point for the entire OS. It performs three critical tasks before anything else runs:
- Adds
/apis/topackage.pathso Lua’srequirecan find CookieOS modules. - Loads
apis/cUtils.luainto the globalcosUtilsvariable. - Sets two global flags:
_G.cosv = "CookieOS v2.2.5"(the version string displayed throughout the UI) and_G.developmentMode = true(controls whether Ctrl+T can terminate programs and whether timing info is shown on the loading bar).
loading.lua cleans up installer artefacts left behind after a fresh install (json, .install, README.md, .gitignore, .vscode) and then renders the loading screen — a yellow CookieOS version watermark centred on screen, followed by an animated blue loading bar. Once the bar completes, it hands off to the next two startup files and then launches the menu.
2. startup/replacements.lua
Patches the live shell and OS environment with CookieOS enhancements. This includes overriding shell.resolveProgram to prefer /programReplacements/, extending shell.setDir to persist the last working directory to disk, wrapping os.reboot and os.shutdown with a graceful “Goodbye” screen, overriding os.version to also return the cosv string, and adding fs.attributes2 — an enhanced version of fs.attributes that formats file sizes and returns human-readable relative timestamps.
3. startup/startEvents.lua
Scans the os/events/ directory for .lua files, loads each one as a coroutine-based event handler, and launches each handler in its own multishell tab. This is how background processes (such as the Gemini chat listener in os/events/geminichat.lua) run concurrently alongside the foreground menu.
4. .menu
The interactive start menu itself. This file runs an event loop that draws the centred menu box, polls for Up/Down/Enter key events, and dispatches to one of five options: Command, Programs, Power, Uninstall, or Help. After a selection is made and the launched program exits, .menu is re-run so the user always returns to the start menu.