This release is a pre-release and may not be stable for production use.
Baldur's Gate 3 Mod Studio & Mod.io Toolkit
An all-in-one workspace for authoring, cataloging, synchronizing, and testing Baldur's Gate 3 mods on mod.io, backed by autonomous AI development workflows.
I started this with the intention of learning how to use AI by helping me keep track of what all the different BG3 mods I had installed actually did, then I started using it to help me theorycraft modded character builds. Then I decided I wanted to make my own mods that built on top of other mods without conflicts.
It has since snowballed into an entire agentic mod studio that runs (almost) completely within VS Code! (you still need to install the official Larian Mod Toolkit in order to actually publish your mods to mod.io)
Features Overview
This project focuses on a conversational, AI First approach to Mod Discovery, Build/Theory Crafting, and Custom Mod Authorship.
Looking for new mods to spice up your next playthrough? Run /bg3-search-mods and tell it roughly what you're up for. Need help optimizing your party's leveling paths and gear loadouts across dozens of installed mods? Launch /bg3-create-build-guide and tell it what you want out of the character. Want to create your own mod to customize your character's journey? Start with /bg3-create-mod, describe your vision, and see where it takes you!
For a deep-dive into feature & functionality specifics, as well as example agent prompts, see docs/FEATURES.
Mod Discovery & Cataloging
- Smart mod.io Search & Filtering: Discover community mods across PC, PS5, and Xbox Series X|S using natural language queries and compatibility filters (
/bg3-search-mods,bg3 modio search). - Automated Unpacking & Asset Extraction: Download and decompress PAK/ZIP archives on demand, extracting engine XMLs, localization tables, and game stats into human-readable markdown (
/bg3-document-mods,bg3 modio extract). - Master Mod Catalog: Track mods centrally in your externalized User Content Studio (
$XDG_DOCUMENTS_DIR/BG3_Mod_Studio/Mods/subscribed/library.md) using Mod Id, Mod Name, Mod Slug, Description, Features Documented, and Spec Link; unverified IDs remain blank. - Conflict & Load Order Analysis: Proactively audit candidate mods for stat collisions, duplicate UUIDs, and console load order dependencies before installing (
/bg3-check-mod-conflicts). - Upstream Update Tracking: Check for upstream patches and updates across tracked mods, refreshing documentation without manual data re-entry (
/bg3-update-mod-documentation,bg3 modio update).
Build Crafting
- Level 1–20 Progression Design: Plan complete 20-level multiclass builds leveraging expanded progression frameworks like UnlockLevelCurve (
/bg3-create-build-guide). - Catalog-Wide BiS Gear Queries: Query the documented mod library for Best-in-Slot weapons, armor, passives, and spell synergies tailored to specific build archetypes (
/bg3-query-gear). - Tactical Combat Sequences: Script turn-by-turn combat openers and action economy allocations (actions, bonus actions, reactions, spell slots) to maximize tactical output.
- Sandboxed Build Guides: Keep build guides organized and isolated in
BG3_Mod_Studio/Build_Guides/without cluttering version control or game directories.
Custom Mod Authorship (5-Stage Shift-Left Lifecycle)
- Stage 1 (Creation:
/bg3-create-mod): Autonomous scaffolding underBG3_Mod_Studio/Mods/authored/<slug>/, parallel subagents for stats/progressions/loca/docs, and read-only validation. - Stage 2 (Diagnostics & Toolkit Sync:
/bg3-diagnose-mod): Phase 2A static checks, game data sync (with binary.locacompilation), and Toolkit (Glasses.exe) log generation prompt -> Phase 2B runtime log diagnosis, automated fixes, and verification loop. - Stage 3 (In-Game Testing:
/bg3-test-mod): Standalone.pakpackaging (--publish-local), load order activation (/bg3-manage-load-order), and save-game compatibility audits (bg3 save inspect). - Stage 4 (Release Prep:
/bg3-release-prep): Atomic semantic version bump, strict validation, GFM HTML description rendering (bg3 mod render-desc), and distribution.pakpackaging. - Stage 5 (Post-Release:
/bg3-post-release): Review allowed tags, preview API mutations, and publish metadata to mod.io via REST API (bg3 modio update-metadata).
Quickstart
1. Prerequisites
- Python 3.10+ with the uv workspace package manager (automatically bootstrapped by
./setup.sh) andpyyaml>=6.0. - Baldur's Gate 3 (installed via Steam on WSL, Linux, or Windows).
- mod.io Account (API Key & Personal Access Token from mod.io/me/access).
2. Run the Interactive Setup Wizard
Run the setup script to configure your environment variables:
./setup.sh
The wizard will:
- Prompt for your
MODIO_API_KEYand optionally test it live against the mod.io Baldur's Gate 3 API. - Prompt for your
MODIO_PAT(Personal Access Token). - Detect your OS/WSL environment and configure your game's
Datapath (BG3_DATA_DIR). - Set your default mod author name (
BG3_MOD_AUTHOR). - Save your settings securely to
$XDG_CONFIG_HOME/bg3/env(mode 0600). - (Optional) Link a remote GitHub repository via GitHub CLI (
gh).
You can review your configuration anytime with:
./setup.sh --check
Directory Layout
BaldursGate3/
├── .agents/skills/ # Autonomous AI agent workflows (15 specialized skills)
├── docs/ # Technical documentation & guides
│ ├── ARCHITECTURE.md # System architecture and design
│ ├── FEATURES.md # Features, workflows, and example agent prompts
│ ├── MOD_CREATION_WORKFLOW.md # Step-by-step mod authoring guide
│ └── MODIO_INTEGRATION.md # mod.io API and library reference
├── packages/ # Modular Python workspace packages
│ ├── bg3-core/ # Shared core runtime, XDG path resolvers, and mod.io client
│ ├── bg3-theorycraft/ # Theorycrafting, progression, and gear optimization tools
│ └── bg3-authoring/ # Mod scaffolding, packaging, and diagnostic toolchain
├── tests/ # Automated test suites
├── .gitignore # Production-grade gitignore
├── setup.sh # Setup wizard launcher
├── CONTRIBUTING.md # Contribution guidelines
├── CODE_OF_CONDUCT.md # Contributor Covenant v2.1
├── LICENSE # MIT License
└── README.md # Project overview
User Content Studio: All user-generated content (build guides, subscribed mods, and custom authored mods) is stored externally in
XDG_DOCUMENTS_DIR/BG3_Mod_Studio(defaults to~/Documents/BG3_Mod_Studio), keeping this codebase completely decoupled from user data.
CLI Reference & Tool Hub
Explore, query, and run any of the 59 registered automation tools via the centralized discovery hub:
# Discover tools by natural language query
bg3 tools search "stat handles"
bg3 tools search "load order"
# Inspect tool flags and schemas
bg3 tools info scaffold stat
bg3 tools info mod pack
# Run query tool directly
bg3 query --slot Weapon --limit 5 --json
5-Stage Custom Mod Lifecycle
# Stage 1: Scaffold and author
bg3 mod create "ArcaneProgression" --json
# Stage 2: Pre-flight validation & game sync
bg3 mod validate arcane-progression --json
bg3 mod sync-game --mods arcane-progression --json
bg3 mod diagnose-logs --mod arcane-progression --severity warning --json
# Stage 3: In-game testing & load order
bg3 mod sync-game --clean-mod arcane-progression --json
bg3 mod pack arcane-progression --publish-local --json
bg3 loadorder enable arcane-progression --json
bg3 loadorder validate --json
bg3 save inspect --audit --json
bg3 save clean-missing --dry-run --json
# Stage 4: Version bump & release prep
bg3 mod bump-version arcane-progression --patch --json
bg3 mod render-desc arcane-progression --write --json
bg3 mod pack arcane-progression --out dist/arcane-progression.pak --json
# Stage 5: Post-release metadata & tags
bg3 modio update-metadata --mod arcane-progression --tags Classes Spells --json
Documentation
- Architecture & Technical Design
- CLI Design & Stream Discipline
- Comprehensive Features & Agent Skills Catalog
- Mod Creation Workflow Guide
- mod.io Integration & Reference Library
Contributing
Contributions are welcome! Please check our Contributing Guidelines and Code of Conduct before opening a pull request.
License
This project is licensed under the MIT License. Baldur's Gate 3 is a registered trademark of Larian Studios. This toolkit is an unofficial community development project.
Metadata
Release files for bg3-mod-studio 1.0.0b1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| bg3_mod_studio-1.0.0b1.tar.gz | 367.7 kB | Without provenance | Details for bg3_mod_studio-1.0.0b1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| bg3_mod_studio-1.0.0b1-py3-none-any.whl | Python 3 | none | any | Details for bg3_mod_studio-1.0.0b1-py3-none-any.whl |
Total release size: 374.1 kB
Release files / bg3_mod_studio-1.0.0b1.tar.gz
| Download URL | bg3_mod_studio-1.0.0b1.tar.gz |
|---|---|
| Size | 367.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4e621e85da7461f7acba17b86746e15156c0b25fa217c0fb232c63ea2bd8eb1c
|
|
BLAKE2b-256 checksum How to use checksums |
6a51e9323fa876ee90816cc4bace5540d7ad0510982278a7550573cc3ee0c701
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / bg3_mod_studio-1.0.0b1-py3-none-any.whl
| Download URL | bg3_mod_studio-1.0.0b1-py3-none-any.whl |
|---|---|
| Size | 6.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e535369e74d14b283b9fb8691f03796627fe8cf5a28fe8711a647309c7b02d54
|
|
BLAKE2b-256 checksum How to use checksums |
fca0b3dd2244bdf0926eb2e2a6ebeae7631c8e76c1ee2f6140b4c45b382746b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Security for bg3-mod-studio 1.0.0b1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.