English | 中文

Lucy

^{The modern Minecraft server package manager}

Declare the mods, plugins, and server cores you want. Lucy resolves exact versions and dependencies, writes a lock file, and keeps your managed scope in sync. Point it at an existing directory and it picks up from what's already there — or start fresh, either way.

cd your-server
lucy init                         # Set up Lucy in this directory
lucy add fabric/lithium@latest    # Resolve exact version + dependencies
lucy install                      # Sync managed scope from the lock file

• Declare packages in the manifest. Lucy resolves exact versions and checksums. lucy install fetches and places them.
• lucy init discovers your runtime, platform, and installed packages, then asks what to manage. Everything else stays untouched.
• Lucy builds a graph of your runtime — Fabric, Forge, MCDR, Paper, Velocity — mapping roles, capabilities, and risk levels. This graph powers lucy status, init discovery, and compatibility resolution.

go install github.com/mclucy/lucy@latest

mkdir my-server && cd my-server
lucy init                         # Take over this directory
lucy add fabric/fabric-api@latest # Add a mod — dependencies resolve automatically
lucy status                       # See what's detected
lucy install                      # Sync managed packages from the lock file

Probe the directory, discover the server environment, and create state files.

lucy init
lucy init --yes --game-version 1.21.4
lucy init --conflict abort

Creates lucy.yaml and lucy-lock.yaml in the project root.

Add mods, plugins, or server cores to the manifest. Lucy resolves exact versions and rewrites the lock file.

lucy add fabric-api
lucy add fabric/lithium@latest
lucy add mcdr/example-plugin@compatible

Remove packages from the manifest. Prunes unused transitive dependencies from the lock.

lucy remove fabric/lithium

Apply the lock file to the managed runtime. Uses exact lock data when current, falls back to manifest intent when stale.

lucy install

Search across sources with filtering and sorting.

lucy search fabric/carpet
lucy search carpet --source modrinth --index downloads --platform fabric

Display what Lucy detects in the current directory: game version, server core, platform, topology, runtime activity, risk signals, and installed packages.

lucy status
lucy status --json --long

Get metadata, description, authors, and version history for a package.

lucy info fabric/fabric-api@latest --long

Display the dependency tree.

lucy tree --live --depth 2

List packages with no dependents. Use this to find what's safe to remove.

lucy leaves --live

lucy cache ls              # List cached downloads
lucy cache clear           # Clear all cached downloads
lucy cache slugs ls        # List slug-to-package-ID mappings
lucy cache slugs clear     # Clear slug mappings

Registered but not yet implemented:

[platform/]name[@version]

Only the name is required. Omit the platform and Lucy infers it from the environment. Omit the version to get @compatible (newest match for your server).

fabric/fabric-api@1.2.3
   ↑       ↑        ↑
platform  name   version

@latest is the newest available. @compatible is the default — best-effort match against the detected environment.

Platforms accepted in the manifest: none, fabric, forge, neoforge, mcdr

The type system also knows bukkit, sponge, velocity, and bungeecord for topology detection, but you can't set these as the primary platform yet.

Data sources: modrinth, curseforge, github, mcdr (hangar and spiget are defined but not yet wired into the resolver).

Intent and config live in lucy.yaml. Resolved facts (versions, hashes, install paths, provenance) live in lucy-lock.yaml.

Lucy builds a graph of your server's runtime. Each node (Fabric, Forge, Paper, MCDR, Geyser, Velocity) carries a role, a set of capabilities (fabric_mods, bukkit_plugins, mcdr_plugins), and a risk level. Edges describe how nodes relate: one adapts another, one bridges to another. This graph powers lucy status, init discovery, and compatibility resolution.