Philosophy
agentic-fm is built on a carefully designed interaction model between AI agents and FileMaker's closed environment. This page describes the principles, constraints, and patterns that make reliable AI-generated FileMaker code possible.
Core Principle
The goal is to create FileMaker scripts in the clipboard-supported format of fmxmlsnippet.
AI operates within a structured workspace where every folder has a specific role:
- sandbox/ — where all newly created or in-progress scripts are stored
- CONTEXT.json — the primary source of IDs, names, relationships, and metadata for the current request, generated by FileMaker and scoped to exactly the objects available for the task
- context/ — pre-extracted index files from the exploded XML, used as a secondary lookup source
- xml_parsed/ — the full XML output from the FileMaker solution, used only as a last resort
- snippet_examples/ — canonical XML templates that define the correct structure for every step type
Step-Level Editing, Not Whole-Script Generation
The primary unit of work is the individual script step, not the full script. Iterating on whole scripts is impractical because FileMaker has no diff/merge and every paste adds new steps to what is already in the script. Working at the step level is faster and far less destructive or duplicative.
When creating new scripts, AI generates a sequence of steps as an fmxmlsnippet which
is pasted directly into FileMaker. When modifying existing scripts, AI references the human-readable
version in scripts_sanitized/ to understand the logic and identify lines to change.
Output Format Rules
Output XML in fmxmlsnippet format wrapped in <fmxmlsnippet type="FMObjectList">
Do NOT wrap output in <Script> tags — output steps only
Use the simplified fmxmlsnippet syntax from snippet_examples, not the verbose XML from xml_parsed/scripts
The id attribute of most tags can be 0 — FileMaker auto-assigns on paste
Context Hierarchy
The context system is designed to minimize token consumption while maximizing accuracy. AI follows a strict lookup order:
CONTEXT.json (primary)
Generated by FileMaker and scoped to the current task. Contains tables, fields, relationships, scripts, layouts, and value lists. All IDs are ready to use directly in output.
Index files (secondary)
Pipe-delimited lookup tables in agent/context/*.index covering the entire solution. A single grep is far cheaper than searching hundreds of XML files.
xml_parsed (last resort)
Only fall back to searching xml_parsed/ if the needed information is not in CONTEXT.json or the index files. Prefer scripts_sanitized/ for understanding logic.
Mandatory AI Workflow
Before writing any script step, AI must follow this exact process:
Clipboard Handling
FileMaker objects are transferred via the macOS clipboard using proprietary binary descriptor classes — they
are not plain text. pbpaste and pbcopy must never be used; they
corrupt multi-byte UTF-8 characters (≠, ≤, ≥, ¶) that
are common in FileMaker calculations.
The helper script clipboard.py handles both directions and auto-detects the correct
clipboard class from the XML content.
Constraints
XML in xml_parsed/ is NEVER modified. It is only referenced.
XML in snippet_examples/ is NEVER modified by AI. Only updated by the developer.
Index files in context/ are NEVER manually edited. They are regenerated by fmcontext.sh.
CONTEXT.json is generated by FileMaker. It should not be manually created or modified by AI.
Token Efficiency
The context system is designed to minimize token consumption:
- CONTEXT.json first — contains exactly what's needed for the current task. Read once at the start.
- Index files are small — each covers the entire solution in a compact pipe-delimited format.
- Never read full xml_parsed files when CONTEXT.json or index data has the answer.
- Prefer scripts_sanitized for understanding logic — ~90% smaller than raw XML.
- Avoid layout XML — it is extremely verbose (75% noise) and rarely needed for script creation.
Ready to bring AI into your FileMaker workflow?
agentic-fm is open source and free to use. Star the repo to follow development, or jump straight into the installation guide.