Content
# Baldur's Gate 3 AI Teammate
Baldur's Gate 3 AI Teammate is an experimental interpretation of what a human-AI teammate can be: not merely a chatbot that gives advice, but a companion that can observe the game, remember what happened, communicate, and control a second-player character in Baldur's Gate 3. It can be connected to Claude Code, OpenAI Codex, or another MCP-compatible AI client for shared play and AI companionship.
A BG3 Script Extender Lua mod exchanges JSON files with a Node.js MCP server, giving the model structured scene, combat, movement, spell, chat, and memory tools instead of relying only on screenshots.
The current reference configuration uses Astarion as the controlled character and suppresses selected Astarion personal-story dialogs. The character GUID and takeover behavior are configurable, while the dialog blacklist remains Astarion-specific.
## Why this exists
This began as a spur-of-the-moment experiment by an author who wanted someone to play co-op with when no human teammate was available. It asks a simple question: can an AI do more than offer walkthrough advice and instead enter the game, understand the situation, take actions, and accompany a player as a real teammate?
The technology is still immature, and the project has many rough edges. The author's time, energy, and token budget are limited, so development is paused for now. Rather than leave the work in private storage, it is being released for everyone with a similar idea to study, test, adapt, and carry forward—and to explore new possibilities for games in the age of AI.
## Project status
This repository is a research prototype, not a polished gameplay mod. It was tested on Windows with BG3 Script Extender v28-era APIs. Game updates and Script Extender changes may require adjustments.
## Architecture
```text
BG3 + BG3SE Lua mod
│ JSON files in the Script Extender data directory
▼
Node.js middleware (MCP over stdio)
│ structured tools
▼
MCP-compatible AI client
```
The bridge is local-only. It does not contain a hosted service, account integration, telemetry, or bundled game assets.
## Requirements
- Windows 10 or 11
- Baldur's Gate 3
- BG3 Script Extender with Lua enabled
- Node.js 20 or newer
- LSLib `Divine.exe` only when building the mod package from source
- An MCP-compatible client
## Quick start
Install middleware dependencies:
```powershell
Set-Location .\middleware
npm ci
npm test
```
Build the mod package with your own LSLib installation:
```powershell
Set-Location ..
.\scripts\package-mod.ps1 -DivinePath 'C:\Tools\Divine.exe'
.\scripts\package-release.ps1
```
Install the generated package and the default runtime configuration:
```powershell
.\scripts\install.ps1
```
Add `BG3AgentBridge` to the active BG3 mod load order with BG3 Mod Manager or an equivalent mod manager, then export/apply that load order. Copying the `.pak` into the Mods directory makes it available but does not by itself prove that the game loaded it.
Copy `examples/mcp.config.example.json` into the configuration format used by your MCP client and replace the placeholder repository path. Start BG3 and load a save. The Script Extender console should contain `BG3AgentBridge LOADED` and `Initial state written`; then call `bridge_status` followed by `ping_lua`.
See [installation](docs/installation.md), [architecture](docs/architecture.md), [protocol](docs/protocol.md), and [limitations](docs/limitations.md) for details.
## Configuration
The Lua runtime reads:
```text
%LOCALAPPDATA%\Larian Studios\Baldur's Gate 3\Script Extender\BG3AgentBridge\config.json
```
Start with `config/bridge.config.example.json`. The middleware also supports these environment variables:
- `BG3_AGENT_BRIDGE_DATA_DIR`: override the Script Extender bridge directory.
- `BG3_AGENT_MEMORY_DIR`: override the local memory directory.
- `BG3_UNPACKED_PUBLIC`: optional path to user-extracted BG3 `Public` data for expanded static combat indexing. No extracted game data is included here.
The personal-dialog suppression and recruitment flags are enabled only when the configured character UUID is Astarion's default UUID. Other controlled characters do not receive Astarion-specific story mutations.
## Safety and scope
The middleware can issue real in-game commands. Use it only in a game session you control. Runtime chat, state, commands, results, and memory are intentionally excluded from version control.
## License and trademarks
Project code is released under the MIT License. Baldur's Gate 3 and its associated names and assets belong to their respective owners. This project is unofficial and is not affiliated with or endorsed by Larian Studios. See `THIRD_PARTY_NOTICES.md`.
MCP Store