poe2-exile-architect

Exile Architect

[English](README.md) · [简体中文](README.zh-CN.md)

Research, create, and understand Path of Exile 2 builds with your AI agent.

Exile Architect connects Codex, OpenCode, and DeepSeek Harness to Path of Exile 2 game data, a local build knowledge base, and Headless Path of Building (PoB). Your agent makes the design decisions; PoB supplies the calculations and the build checks.

[Install](#install) · [Usage](#usage) · [Showcase](#showcase) · [FAQ](#common-questions) · [Contributing](#contributing)

Local knowledge base and PoB validation

• Local knowledge base

Research turns mechanics, component interactions, and usage conditions from existing builds into research records stored on your computer. The knowledge carries across conversations, and Create retrieves relevant records when designing a new build, reusing earlier research.

• Local execution

Game data queries, knowledge storage, and PoB calculations run on your machine, and build files are saved locally. The model uses your agent host's existing configuration; whether online research and model calls use remote services depends on the task and host settings.

• PoB validation

The equipment, skills, and passives designed by the agent are written into PoB before damage, defense, and resource data are read back. The numbers correspond to a specific build and combat configuration and can be checked. Mechanics that PoB does not cover are documented separately, and estimates are shown separately from calculated results.

Three workflows

| I want to… | Use | What I get |

| --- | --- | --- |

| Extract useful knowledge from an existing build | Research · poe-bd-research | Saved explanations of mechanics, component synergies, requirements, and failure cases that future builds can draw on |

| Design a build for a class, skill, and target level | Create · poe-bd-create | Skill, equipment, and passive choices; PoB checks; local build files and a playstyle explanation |

| Understand how an existing build works | Learning · poe-bd-learn | An HTML learning guide with component icons, combat-loop diagrams, explanations, navigation, and search |

Research builds the knowledge base. Create uses it to design builds. Learning teaches you a build without adding it to the knowledge base. You can use each workflow on its own.

Build your own local knowledge base

Study builds you are interested in with Research and keep the findings for later use. Research saves explanations of skill interactions, equipment roles, passive choices, resource recovery, and defenses, along with their requirements, failure conditions, and game versions. Accepted findings stay on your machine and remain available in future conversations.

When you ask for a new build, Create searches this knowledge base for research relevant to the class, skills, and target version. Your agent uses those findings to make design decisions, assembles a build at the requested level, and checks it with PoB. Studying builds in a playstyle you enjoy can give future Create requests more mechanics and alternatives to consider.

For example, research a few Spark builds, then ask Create for a level 90 Spark build using the related local research. The saved knowledge informs the new design; its equipment, resource requirements, and calculated performance are checked again for the new build. Missing evidence and unmodelled mechanics remain explicit in the result.

Install

Exile Architect installs from a source checkout, and your agent starts its tools from that folder — keep it in place after installation.

1. Install the prerequisites

• [Git](https://git-scm.com/downloads) and [uv](https://docs.astral.sh/uv/getting-started/installation/). uv can install the required Python version for you.
• An agent host: Codex, OpenCode, or DeepSeek Harness, with model access already configured. Research requires a host that gives subagents access to MCP tools.
• LuaJIT 2.1, used to run the PoB calculation engine:

| System | LuaJIT installation |

| --- | --- |

| Windows | Install [MSYS2](https://www.msys2.org/), open its UCRT64 terminal, and run pacman -S mingw-w64-ucrt-x86_64-luajit. The standard C:\msys64\ucrt64\bin\luajit.exe location is detected automatically. |

| macOS | With Homebrew installed, run [brew install luajit](https://formulae.brew.sh/formula/luajit). |

| Ubuntu / Debian | Run sudo apt-get update followed by sudo apt-get install luajit. |

For a nonstandard LuaJIT location, set POB_LUAJIT to the executable's absolute path in the environment used by your agent host. Node.js 20+ is optional, for Build Planner .build export.

2. Download the project and PoB

Run these commands in PowerShell on Windows, or a terminal on macOS / Linux:

git clone https://github.com/avdergh/poe2-exile-architect.git
cd poe2-exile-architect
uv sync --python 3.12

git clone --filter=blob:none --no-checkout https://github.com/PathOfBuildingCommunity/PathOfBuilding-PoE2.git pob/PathOfBuilding-PoE2
git -C pob/PathOfBuilding-PoE2 config core.autocrlf false
git -C pob/PathOfBuilding-PoE2 checkout ce566eac45ea8a86477f513c7ee65a1ebe60014e

Use this pinned PoB revision with the patches below. Installing the PoB desktop application alone does not supply this headless runtime.

3. Apply the patches and connect your agent

Choose your system. The examples install for Codex; replace codex with opencode if you use OpenCode. DeepSeek Harness installs through its own preset — see the end of this step.

Windows PowerShell

Get-ChildItem .\pob\patches\*.patch | Sort-Object Name | ForEach-Object {
    git -C pob/PathOfBuilding-PoE2 apply --ignore-whitespace $_.FullName
    if ($LASTEXITCODE -ne 0) { throw "PoB patch failed: $($_.Name)" }
}
.\install.ps1 -FromCheckout codex

macOS / Linux

(cd pob/PathOfBuilding-PoE2 && git apply --ignore-whitespace ../patches/*.patch)
bash install