Foliacode: Instructions file for Codex

AGENTS.md — driving FoliaCode from an AI assistant

This file tells a coding assistant (Claude Code, Codex, Cursor, Copilot, or any agent framework) how to operate FoliaCode correctly. It is written to be read by a machine and acted on without further explanation.

If you are a human, you probably want README.md instead.

---

The one rule that matters

analyze is always safe. verify executes downloaded third-party code — ask the user before you run it. transform writes a new JAR — dry-run it first.

foliacode analyze only reads bytecode. It touches no network, starts no process, and changes no file unless --json is given. Run it freely.

foliacode verify downloads a Folia server jar from PaperMC and executes it on the user's machine. It is gated behind explicit consent (--yes, or enabled: true in foliacode.yml) precisely so that an agent cannot enable it by accident.

Do not pass --yes on your own initiative. Ask first, in plain language:

"I can also boot a throwaway Folia server to confirm the plugin actually loads. That downloads a ~50 MB server jar from PaperMC and runs it locally for about a minute, then deletes it. Want me to?"

If the user has already put enabled: true in foliacode.yml, that is their standing consent and you may run verify without asking again.

foliacode transform never modifies the input JAR — it writes a new one beside it — so it is not destructive. But it produces an artifact the user may deploy, so run --dry-run first and show them what would change before writing anything. Never describe a transformed JAR as "Folia-ready": say which call sites were rewritten and which were refused.

---

Quick reference

# Static analysis — safe, offline, fast (~0.4s for 2000 classes)
foliacode analyze MyPlugin.jar

# Every JAR in a directory
foliacode analyze plugins/

# Machine-readable output for you to parse
foliacode analyze plugins/ --json report.json

# Gate a CI job on thread-safety issues, not just fatal ones
foliacode analyze plugins/ --fail-on HIGH

# Show every call site instead of the first three per rule
foliacode analyze MyPlugin.jar --verbose

# List the rule set (useful for explaining a finding to a user)
foliacode rules

# Real server boot — ONLY after the user agrees
foliacode verify MyPlugin.jar --yes --memory 2048

# Boot with dependency plugins installed alongside
foliacode verify MyPlugin.jar --yes --with Vault.jar --with ProtocolLib.jar

# Boot and record which flagged calls actually ran, and on which threads
foliacode verify MyPlugin.jar --yes --instrument

# See what a rewrite would change — safe, writes nothing
foliacode transform MyPlugin.jar --dry-run

# Write the rewritten JAR (the original is left alone)
foliacode transform MyPlugin.jar --json transform.json

# Print the -javaagent line for a server the user runs themselves
foliacode agent MyPlugin.jar