IsaacAgent

An AI coding agent for The Binding of Isaac: Repentance Lua mod development.
It provides a Cursor/OpenCode-like desktop experience with Isaac-specific
knowledge, tools, and workflows built in.

Quick Start

1. Get the App

Option A — Build from source (requires .NET 8 SDK):

git clone https://github.com/Skymly/IsaacAgent.git
cd IsaacAgent
dotnet build IsaacAgent.sln -c Release
dotnet run --project src/IsaacAgent.App/IsaacAgent.App.csproj -c Release

Option B — Publish a single-file executable:

./build.ps1 --target Publish --configuration Release
.\artifacts\publish\win-x64\IsaacAgent.exe

2. Configure LLM

On first launch, open Settings (Ctrl+,) and configure:

For embeddings (RAG), ONNX is the default — a bundled
all-MiniLM-L6-v2 model ships with the app (no extra download). You can
switch to Ollama in Settings if you prefer a remote embedder.

3. Start Coding

1. Ctrl+N — New project (or Ctrl+Shift+T to pick a template)
2. Type your request in the chat box, e.g. "Create a passive item that doubles fire rate"
3. The agent will scaffold files, write code, and validate XML automatically
4. Ctrl+Enter to send, Ctrl+K to clear chat

Features

Core

• Chat-driven mod development — streaming assistant responses with
  tool-calling for file operations, scaffolding, diagnostics, API lookup,
  and semantic knowledge search.
• Isaac API knowledge base — built-in enums, classes, and callbacks for
  the vanilla API (74 callbacks) plus REPENTOGON extensions (130+ callbacks).
• Local RAG search — semantic search over 480+ embedded modding docs
  (MkDocs chunker + bundled ONNX all-MiniLM-L6-v2 by default, or Ollama;
  in-memory vector store with on-disk index cache).
• Multi-provider LLM — any OpenAI-compatible endpoint (MiniMax, OpenAI,
  local servers) or Ollama.
• Project-aware tools — file operations are sandboxed to the opened
  project directory; XML/Lua escaping and path-traversal guards are built in.
• Encrypted credential storage — API keys are protected with DPAPI
  (CurrentUser scope) on Windows.
• Persistent chat history — per-project history is saved and restored
  across restarts.

UI Features

Agent Tools

The agent has access to 16 tools across two modules:

IsaacAgent.Tools (file operations, scaffolding, API knowledge, project commands):

IsaacAgent.Rag (semantic search, validation, log parsing):

Skills

Skills are higher-level workflows that augment the agent's behavior for specific
Isaac modding tasks. They sit between the system prompt and atomic tools:
each skill injects task-specific guidance and pre-fetches relevant RAG context
before the LLM processes the request. Skills activate automatically when the
user's message matches a keyword pattern, or explicitly via a slash command
(type / in the chat box or pick one from the command palette).

Knowledge Base

• 480+ Markdown docs — vanilla + REPENTOGON API documentation
• 25 code patterns — collectible (passive/active), familiar (basic + advanced), boss, room, challenge, character, trinket, card/pill, curse, door, pedestal, shop, devil room, tear effect, HUD, music, cutscene, status effect, save data, achievement tracking, item pool modification, multiplayer sync, REPENTOGON ImGui menu
• 35 XSD schemas — official Isaac XML validation schemas
• 74 vanilla callbacks with canonical IDs (0-73)
• 130+ REPENTOGON callbacks (IDs 1000+) with override tracking
• Isaac classes with method listings
• Enums with value descriptions
• 5 few-shot workflows — create collectible, debug runtime error, validate project, add save data, create familiar (embedded in system prompt to guide multi-step tool orchestration)

Tech Stack

• .NET 8 + Avalonia 11 + CommunityToolkit.Mvvm
• MVVM architecture, multi-project solution
  (App / Core / LLM / Tools / Agent / Rag)

Prerequisites

• .NET 8 SDK
• Windows x64 — the only officially supported platform (SupportedOSPlatform: windows; see ADR-003). macOS / Linux are not supported.
• An LLM API endpoint (OpenAI-compatible or Ollama)

Configuration

Set environment variables or create a config file:

# Environment variables — ISAAC_AGENT_API_KEY is required to use env-based config.
# ENDPOINT and MODEL fall back to defaults if omitted.
set ISAAC_AGENT_API_KEY=your-api-key
set ISAAC_AGENT_ENDPOINT=https://api.minimax.chat/v1
set ISAAC_AGENT_MODEL=abab6.5s-chat

# Or for Ollama
set ISAAC_AGENT_ENDPOINT=http://localhost:11434
set ISAAC_AGENT_MODEL=llama3

Or place a config.json in %APPDATA%\IsaacAgent\. The API key is
encrypted with DPAPI (CurrentUser scope) and stored in EncryptedApiKey:

{
  "ProviderType": "OpenAICompatible",
  "Endpoint": "https://api.minimax.chat/v1",
  "Model": "abab6.5s-chat",
  "EncryptedApiKey": "<base64 DPAPI ciphertext>"
}

The config file is normally managed by the Settings UI; you rarely need
to edit it by hand. If you do, leave EncryptedApiKey empty and set the
key via environment variable or the Settings dialog.

Build & Run

# Via Nuke (CI-authoritative)
./build.ps1 --target Ci --configuration Release

# Or traditional dotnet
dotnet build IsaacAgent.sln -c Release
dotnet run --project src/IsaacAgent.App/IsaacAgent.App.csproj -c Release

Tests

# Via Nuke
./build.ps1 --target Ci --configuration Release

# Or traditional dotnet
dotnet test IsaacAgent.sln

Publish a Single-File Executable

# Via Nuke (CI-authoritative, includes verification)
./build.ps1 --target Publish --configuration Release --runtime win-x64

# Or traditional dotnet
dotnet publish src/IsaacAgent.App/IsaacAgent.App.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -o artifacts/publish/win-x64

Versioning

Versions are derived automatically from Git tags by MinVer.
Pushing a v* tag (e.g. v0.1.0) triggers the CI release job and sets the
assembly/package version. Between tags, the version auto-increments as
pre-release (e.g. 0.1.0-alpha.0.42 where 42 is the commit count since the
last tag). No manual version editing is needed.

git tag v0.1.0
git push origin v0.1.0   # triggers CI release job

Project Layout

src/
  IsaacAgent.App/       Avalonia UI (Views, ViewModels, DI)
  IsaacAgent.Core/      Domain models, interfaces, knowledge base
  IsaacAgent.LLM/       LLM provider abstraction (OpenAI-compatible, Ollama)
  IsaacAgent.Tools/     Agent tools (file ops, scaffolding, diagnostics, API search)
  IsaacAgent.Rag/       RAG pipeline (chunking, embedding, retrieval, XML validation)
  IsaacAgent.Agent/     Agent engine (orchestration, tool routing, prompts)
tests/
  IsaacAgent.Tests/     Unit and integration tests
tools/
  e2e-test/             Standalone E2E test for RAG pipeline (in solution as IsaacAgent.E2ETest)
build/                  Nuke build script

Contributing

See CONTRIBUTING.md for development setup, code
conventions, and pull request guidelines.

License

MIT — Copyright (c) 2026 Skymly