Packages

Packages extend the AI Game Dev app with whole capabilities: Blender, music with SuperCollider, a project Knowledge Base, Tripo 3D generation, local image and video models, cloud video and audio models, and anything a team builds for itself. This page explains what a package is, which packages come with the app, and how to manage them in the desktop Packages window and with the gamedev pkg command.

What a package is#

A package is a folder with a manifest, aigd-package.json, and optionally some JavaScript. The model is the same as VS Code extensions: everything a package shows is declared in its manifest and visible before its code runs, and the code starts only when something needs it.

A package can contribute:

• Session tools in the Tools row, often backed by an MCP server, so the agent gets new tools.
• Slash commands such as /blender or /kb, which work in the desktop chat and in the CLI.
• Commands for the command palette, menus and composer toolbar buttons, status bar items.
• Panels, side-panel views, windows of its own and custom editors or previews for file types.
• Settings, short in-app tutorials, and dependencies on other packages or Claude plugins.
• Pure data: the local image and video models are packages with no code, which declare their files, download size, licence and the hardware they fit.

Every package has an id of the form publisher.name. First-party packages use the publisher aigd, for example aigd.blender.

Packages, Claude plugins, MCP servers and engine extensions#

The app has four kinds of extension. They all end up as tools the agent can use, but they are managed in different places:

An MCP server you add in Settings belongs to the project that was open when you added it and is never visible in other projects. A new plugin or MCP server applies to the chat that is already open from its next message.

Packages that come with the app#

On first start the app installs its default packages for you, at the user level, so they are available in every project:

A default you remove is never added again. Installing a package does not mean every chat carries it: you switch its tools on per session in the Tools row. The local image and video models, and the cloud model families, are separate packages; see the packages catalog for all of them.

The Packages window#

Open it from the package icon in the status bar, at the bottom right of the window ("Open Packages"). It shows the project and its levels at the top, and these tabs:

• Installed: the packages active in this project, with their status, version and level.
• Browse: search the AI Game Dev package registry.
• Claude plugins: the Claude plugins that packages require for this project.
• Models: the local image and video models you can download, shown when the project has the generation runtime.

The header has Check for updates and Reload, which restarts the project's packages. Select a package to see its details, levels, settings and errors.

Install a package#

In the desktop app#

1. Open the Packages window and select Browse.
2. Search, for example hello, and select the package.
3. Under the add button, pick the level: User, Project or Local (see levels).
4. Click Add to Project (or Add to User, Add to Local).

To add a package from outside the registry, type into the add box. It accepts a registry id (aigd.blender, optionally with a version range such as aigd.blender@^1.2), a GitHub link or owner/repo, an npm package (npm:<name> or its npmjs.com link) or a folder path.

In the CLI#

Run gamedev pkg in the project folder (or pass --cwd <path>), or use /packages in the interactive CLI. The default level is --project.

gamedev pkg list                          # the packages in effect for this project
gamedev pkg list --user                   # the user level alone
gamedev pkg add aigd.blender --user       # from the registry, for every project
gamedev pkg add github:owner/repo         # from GitHub, for this project
gamedev pkg add npm:some-package --local  # from npm, this machine only

A registry package added without a range is written as ^<installed version>, so it receives compatible updates.

Levels: user, project, local#

Packages and their settings are declared at three levels. A higher level overrides a lower one: local wins over project, project wins over user.

Each level also has a lock file next to it (packages-lock.json, packages-lock.local.json) that pins the exact versions, so teammates who share a project lock install the same bytes.

Use Project for packages the whole team needs, User for your personal tools, and Local for machine-specific choices, such as a path to a tool installed on your computer.

Exclude a package in one project#

To turn a user-level package off in one project, select it and choose Exclude on the level row, or:

gamedev pkg exclude aigd.blender            # off in this project (written to the project file)
gamedev pkg include aigd.blender            # undo

The project file then holds "aigd.blender": false; other projects are not affected.

Update packages#

Automatic updates are on by default. The app checks shortly after start-up, every four hours and when you click Check for updates. It installs the newest version inside the range each level declares that is compatible with your app, and shows one notification per run, such as "Updating 1 package… (1/1)" followed by "Updated 1 package".

• Turn automatic updates off for one package with its Auto-update switch in the Packages window, or gamedev pkg auto-update off <id>. The choice is per computer.
• Update now with gamedev pkg update (all) or gamedev pkg update <id>.
• Packages from a local folder, and GitHub sources pinned to a tag, never update automatically.

A package that needs a newer app says so ("requires AI Game Dev >=X, you have Y"); update the app first.

Remove a package#

Select it and choose Remove, or:

gamedev pkg remove <id>              # remove it from the project level
gamedev pkg remove <id> --user       # remove it from the user level

A package installed only as a dependency of another one has no Remove, only Exclude; it disappears on its own when nothing needs it.

Package settings#

Select a package and open Settings. Next to each setting you choose the level it is written to; the chip shows where the current value comes from. Some settings are folder pickers with Browse… and a free-space check, some offer choices that come from the app.

In the CLI:

gamedev pkg settings aigd.blender                 # every key, its value and level
gamedev pkg settings <id> <key> <value> --local   # write a value at a level
gamedev pkg settings <id> <key> --unset --project # clear the value at a level

A value is checked against its declared type before it is saved; a refused value changes nothing and exits with code 1.

Dependencies#

A package can depend on other packages and on Claude plugins. The app installs them for you and keeps one version of each package per project. The Packages window lists a dependency as "installed for <id>" with its level. Claude plugins a package needs are installed per project into an app-owned cache and loaded only in that project's sessions, never into your own Claude Code.

Safety and errors#

Packages run with your user's permissions, like VS Code extensions: there is no sandbox. Install packages only from sources you trust. Packages from the AI Game Dev registry are verified against their published checksums before they are unpacked.

If a package fails, its card shows a warning count and its Errors tab lists the details. Errors of third-party packages are never sent anywhere; errors of first-party aigd packages from our registry are reported to us only with your crash-reporting consent. Installed packages start without a network connection.

Next steps#

• See every available package in the packages catalog.
• Build your own in Creating packages.
• The post packages, Claude plugins and MCP servers shows the Packages window and a project MCP server in action.