Balatro Mod Development

Create and debug Balatro mods with Steamodded, Lovely, and SMODS.

Quick Agent Selection

When researching, spawn the right agent:

Parallel: When researching DIFFERENT sources – spawn multiple agents at once Sequential: When second query depends on first result

⚠️ MANDATORY: Sub-Agent Invocation

ALWAYS use scripts/run_subagent.sh to spawn sub-agents. This adapter resolves backend config from mod.config.json and routes through codeagent.

DO NOT use built-in agent spawning, direct shell commands, or any other method.

# CORRECT - always use this
./scripts/run_subagent.sh game-source-researcher <<'EOF'
[task content]
EOF

# WRONG - never do this
# spawn_agent(...), create_subagent(...), direct codeagent calls, etc.

See references/sub-agents.md for boundaries, workflow patterns, and creating new agents.

Repo Type Awareness

Auto-detection: Compare mod manifest author with git remote username.

# Get git remote username
git_user=$(git remote get-url origin 2>/dev/null | sed -E 's|.*[:/]([^/]+)/[^/]+\.git$|\1|' | tr '[:upper:]' '[:lower:]')

# Get mod author from manifest (first author, lowercase)
mod_author=$(jq -r '.author[0] // .author // ""' *.json 2>/dev/null | head -1 | tr '[:upper:]' '[:lower:]')

# Compare: match = own, no match = fork
[[ "$git_user" == "$mod_author" ]] && echo "own" || echo "fork"

See templates/project-rules-template.md for detailed rules per type.

File Naming Convention (Claude & Codex)

Both Claude and Codex use the same file structure:

AGENT.md Purpose: Enable seamless handover between agents. Another agent should quickly understand mod structure, functions, dependencies, and current development status without losing context.

File Placement Rules

Only these .md files belong in root:

• README.md, README_zh.md
• CHANGELOG.md, CHANGELOG_zh.md
• AGENT.md, INIT.md
• LICENSE.md

ALL other .md files MUST go in docs/

External References (No Symlinks Needed)

Access reference code directly via absolute paths. No setup required.

Source Locations (macOS)

Source Locations (Windows)

Finding Patterns & Examples

When you need to find how something is implemented:

Key Dependencies

Pattern References

Read these files for specific topics:

New Mod Setup (type: new)

Templates in templates/ folder:

Meta Files:

User Docs in templates/docs/:

Required User Docs (new repos):

Root:
├── README.md, README_zh.md      # Main docs (EN/ZH)
├── CHANGELOG.md, CHANGELOG_zh.md # Version history (EN/ZH)
└── {ModName}.json, manifest.json # Meta files

docs/:
├── description.md               # Concise README
├── NEXUSMODS_DESCRIPTION.txt    # BBCode format
├── knowledge-base.md            # Issues & lessons
└── AGENT.md                     # Repo structure (AI)

Basic Mod Structure (new repos):

{ModName}/
├── main.lua                 # Entry point, mod registration
├── config.lua               # Config defaults (optional)
├── lovely.toml              # Lovely patches (if needed)
├── {ModName}.json           # SMODS mod manifest
├── manifest.json            # Thunderstore manifest
├── mod.config.json          # Script configuration
├── Utils/
│   └── Logger.lua           # Centralized logging
├── localization/
│   ├── en-us.lua            # English (required)
│   └── zh_CN.lua            # Chinese
├── assets/                  # Sprites, shaders
├── scripts/                 # Utility scripts
└── docs/                    # Documentation

AI Agent Config Templates

Logging

For new/my repos:

Use Utils/Logger.lua (from templates/logger-template.lua):

local Logger = require("Utils.Logger")
local log = Logger.create("ModuleName")
log("info", "Initialized")
log("error", "Failed: " .. err)

For forks/others’ repos:

Use temp logs only (remove before PR):

pcall(print, "[Debug] checkpoint: " .. tostring(var))

Utility Scripts

Workflow: Init Any Existing Repo

For ALL non-empty repos (own or fork), ALWAYS do these first:

1. Delete References/ folder if exists (legacy symlink approach)
2. Move extra .md files to docs/ – only keep in root: README*.md, CHANGELOG*.md, AGENT.md, INIT.md, LICENSE.md
3. Add dev files (if missing): AGENT.md, INIT.md, mod.config.json, scripts/sync_to_mods.sh
4. Add Claude config (if missing): .claude/commands/, .claude/hooks/, .claude/agents/
5. Update .gitignore with agent folders

Then for OWN repos: Also check manifest, scripts version (2.0.1), add create_release.sh, Logger.lua

Then for FORK repos: Keep AGENT.md lightweight, use fork-mode INIT.md, don’t add release scripts

Workflow: Debugging

1. Check references/lua-gotchas.md for known pitfalls (FFI cdata, nil scoping, boolean normalization)
2. Check platform (desktop vs mobile)
3. Search game source for function
4. Check other mods for implementations
5. Add logs (Logger.lua for own, temp for fork)
6. Check Lovely logs
7. If fix fails 3+ times: Document in docs/knowledge-base.md

Workflow: Update User Docs

When user says “update all user docs”:

1. Review ALL files: README(_zh).md, CHANGELOG(_zh).md
2. Review docs/: description.md, NEXUSMODS_DESCRIPTION.txt
3. Update version in {ModName}.json, manifest.json
4. Ensure EN/ZH consistency

Workflow: Draft PR Message (fork repos)

Use /draft-pr command. Style: 3-5 sentences, casual tone, what/why/done.

Sub-Agents for Research

Main agent handles code. Sub-agents handle information gathering via scripts/run_subagent.sh → codeagent routing.

Backends and source paths are configurable in mod.config.json:

• agent_backends.research / agent_backends.execution — category defaults
• agent_backends.overrides.{agent-name} — per-agent override (string or {backend, workdir})
• source_paths — where game source, SMODS, mods are located on this machine

Model restriction: Never use Opus for sub-agents. Use Sonnet (research requiring reasoning) or Haiku (pure search/grep/execution). Opus is reserved for the main agent only.

These are backend hints. Codeagent owns final invocation policy (~/.codeagent/config.yaml, ~/.codeagent/models.json). run_subagent.sh resolves config and routes through codeagent automatically — no direct codeagent-wrapper calls.

See references/sub-agents.md for full config resolution, invocation patterns, and parallel examples.

Available Commands

• /familiar – Get familiar with this mod (reads AGENT.md, INIT.md, maps architecture)
• /init-balatro-mod – Initialize new mod
• /sync-mod – Start sync with watch mode (run once at start)
• /bump-version [patch|minor|major] – Increment version, update changelogs
• /release – Create release packages (auto-detects version from manifests)
• /fix-sprites <directory> [--preview] – Fix grey borders on sprites
• /refactor [focus-area] – Review code for redundancy, outdated fallbacks, modularization
• /debug – Verify fix by checking Lovely logs (auto-detects mod key from repo)
• /draft-pr – Draft PR message (for forks)
• /update – Audit project for outdated scripts, hooks, commands, and config
• /update-docs – Review all user docs
• /update-skill [file|instruction] – Update skill based on new knowledge

Sub-agents available after setup:

• game-source-researcher – Find game functions and injection points
• smods-api-researcher – Find SMODS API patterns and usage
• mod-pattern-researcher – Find how other mods implement features
• lovely-patch-researcher – Find Lovely patch syntax and examples
• project-explorer – Extensive codebase exploration (uses codex for token efficiency)
• script-runner – Run temp scripts and return results