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 + step catalog (+ snippet_examples for complex steps) 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.

Alternative: The Webviewer provides a visual alternative to steps 3-5. Write scripts in human-readable format with Monaco autocomplete and live XML preview — the client-side converter handles the HR-to-XML translation automatically.

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/. Uses companion_server.py for shell execution via Insert from URL — no plugin required.

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 specialized AI workflows that extend what the agent can do — from script development and debugging to schema design, data operations, and layout building. Invoke them naturally in conversation.

See the Skills page for the full catalog with descriptions, example prompts, and deployment tier details.

CLI Tools

fmparse.sh

Archives a FileMaker XML export and parses it using fm-xml-export-exploder. Supports the data separation model — each solution file is parsed independently, preserving other solutions' data in xml_parsed/.

./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.

python3 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, reference cross-checks against CONTEXT.json, context staleness warnings (>60 min), and coding convention violations (ASCII comparison operators, variable naming).

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)
python3 agent/scripts/clipboard.py write agent/sandbox/myscript.xml

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

companion_server.py

A lightweight local HTTP server that FileMaker calls via native Insert from URL to execute shell commands. Start it once per session before using the Explode XML or Push Context scripts.

python3 agent/scripts/companion_server.py

Listens on localhost:27631 by default. The FileMaker companion scripts use this server for shell execution.

Step Catalog

agent/catalogs/step-catalog-en.json is a structured JSON reference for all FileMaker script steps. It is the single source of truth for step XML structure — agents grep it to get step IDs, parameter definitions, types, enums, HR signatures, behavioral notes, and Monaco snippets. Behavioral notes previously scattered across snippet_examples/ have been migrated into the catalog's notes field; snippet_examples are now archival and consulted only for complex or unreviewed entries.

The catalog is consumed by CLI/IDE agents (for XML construction), the webviewer (for HR-to-XML conversion and Monaco autocomplete), and validate_snippet.py (for step name validation). See ARCHITECTURE.md for the full field reference.

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.

Knowledge Base

agent/docs/knowledge/ contains curated behavioral intelligence about FileMaker Pro — nuances, gotchas, and practical insights that go beyond what standard help references cover. While AI handles logic and control flow well, FileMaker has platform-specific behaviors that are easy to get wrong without domain-specific guidance.

Each document captures what an experienced FileMaker developer knows intuitively but AI would otherwise miss. AI scans the keyword-indexed manifest at agent/docs/knowledge/MANIFEST.md before composing scripts and reads any matching documents to avoid common pitfalls.

Current topics

Document Covers
found-sets.md Found set attributes, actions on found sets, collecting field values, restoring found sets, snapshot links
single-pass-loop.md Try/catch pattern using a single-pass loop for structured error handling without nested If blocks
variables.md Variable scope, naming conventions, initialization patterns, and common pitfalls
error-handling.md Get(LastError) timing, error capture strategies, and robust error handling patterns
script-parameters.md Passing and parsing script parameters and results using JSON conventions

This is one of the most impactful areas for community contributions. If you know of a FileMaker behavior that AI commonly gets wrong, see the Contributing page.

Webviewer

The webviewer/ directory contains a browser-based visual script editor with a three-panel layout: Monaco editor, live XML preview, and AI chat. It provides an alternative to the CLI/IDE workflow where you write scripts in human-readable format and the client-side converter handles HR-to-XML translation.

See the Webviewer page for setup instructions, embedding details, and AI provider configuration.

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
python3 fetch_docs.py              # fetch everything
python3 fetch_docs.py --steps      # script steps only
python3 fetch_docs.py --functions  # functions only
python3 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 development?

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