Documentation

Everything you need to understand and use agentic-fm effectively.

Background

FileMaker Pro is a closed environment — logic and schema live inside a binary file, not text files. Three XML formats provide the bridge between FileMaker and external tooling:

  • Database Design Report (DDR) — a full solution export. An older format that Claris is moving away from; not used by this project.
  • Save a Copy as XML — the modern export format covering scripts, layouts, schema, and more. This is the format agentic-fm uses as input.
  • fmxmlsnippet — the clipboard format FileMaker uses to copy and paste individual objects. This is the output format AI uses to deliver generated code back into FileMaker.

Workflow

The core workflow is a six-step loop between FileMaker and your AI editor:

1

Export and parse

In FileMaker, run "Explode XML" to export and parse the current solution into agent/xml_parsed/.

2

Push context

Navigate to the target layout and run "Push Context" with a task description. This writes agent/CONTEXT.json.

3

AI generates code

AI reads CONTEXT.json + snippet_examples to generate fmxmlsnippet output in agent/sandbox/.

4

Validate

validate_snippet.py runs automatically to check for structural errors, missing attributes, and unbalanced blocks.

5

Load to clipboard

clipboard.py writes the validated snippet to the clipboard in the correct binary format.

6

Paste into FileMaker

Paste the fmxmlsnippet directly at the desired insertion point in the Script Workspace.

Companion Scripts

filemaker/agentic-fm.xml contains three companion scripts that connect FileMaker to the toolchain. Paste them into your Script Workspace to install.

Get agentic-fm path

One-time setup. Prompts you to select the repo folder and stores the path in $$AGENTIC.FM.

Explode XML

Saves a copy as XML and calls fmparse.sh to archive and explode it into agent/xml_parsed/. Requires the MBS Plugin for shell execution.

Push Context

Prompts for a task description, calls Context($task), and writes the result to agent/CONTEXT.json. Run from whatever layout you are working on before starting an AI session.

Agent Skills

Skills are opt-in workflows that extend AI behavior. Invoke them naturally in conversation.

Skill What it does Example triggers
script-preview Generates a numbered step outline for review before XML generation. "preview the script", "outline the steps"
script-review Code review of existing scripts — logic flow, efficiency, correctness. "review this script", "check the logic"
library-lookup Searches the curated snippet library for reusable code. "use the HTTP request script", "add a timeout loop"

CLI Tools

fmparse.sh

Archives a FileMaker XML export and parses it using fm-xml-export-exploder.

./fmparse.sh -s "Solution Name" /path/to/export.xml [options]

fmcontext.sh

Generates AI-optimized index files from exploded XML. Runs automatically at the end of fmparse.sh.

./fmcontext.sh

validate_snippet.py

Post-generation validator that checks fmxmlsnippet output for common errors. Runs automatically as part of the AI toolchain.

python agent/scripts/validate_snippet.py [file_or_directory] [options]

Checks include: well-formed XML, correct root element, no Script wrapper, step attributes, paired steps (If/End If, Loop/End Loop), known step names, and reference cross-checks against CONTEXT.json.

clipboard.py

Transfers fmxmlsnippet XML to/from the macOS clipboard using the correct binary descriptor classes.

# Write XML to clipboard (ready to paste into FileMaker)
python agent/scripts/clipboard.py write agent/sandbox/myscript.xml

# Read FM objects from clipboard to file
python agent/scripts/clipboard.py read agent/sandbox/output.xml

CONTEXT.json

Generated by the Context custom function in FileMaker before each script generation request. Contains scoped context — only the tables, fields, layouts, scripts, relationships, and value lists relevant to the current task.

The function introspects the live solution using design functions and ExecuteSQL queries against system tables. It automatically discovers:

  • The current layout, its base table occurrence, and named objects
  • All table occurrences referenced on the layout with complete field lists
  • Relationship information via GetTableDDL
  • All scripts, layouts, and value lists in the solution

Because the output is scoped to the current layout's context, AI receives exactly the information it needs without unnecessary noise.

Coding Conventions

All AI-generated FileMaker code follows conventions defined in agent/docs/CODING_CONVENTIONS.md. These cover variable naming prefixes ($, $$, ~, $$~), Let() formatting, operator spacing, boolean values, and control structure style.

You can — and probably should — customize these conventions to match your team's standards. AI reads this file before writing any calculation or script logic and follows whatever rules you define.

FileMaker Reference Documentation

The agent/docs/filemaker/ directory contains a script that fetches official FileMaker Pro reference documentation from the Claris help site and converts it to Markdown. Useful for giving AI agents accurate, up-to-date information about script step options, function syntax, and error codes. 

cd agent/docs/filemaker
python fetch_docs.py              # fetch everything
python fetch_docs.py --steps      # script steps only
python fetch_docs.py --functions  # functions only
python fetch_docs.py --errors     # error codes only

Note: Generated files are copyrighted by Claris International Inc. and excluded via .gitignore. For personal, non-commercial use only.

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.

Installation Guide Star on GitHub