AI Agents

xlflow gives coding agents a stable interface for Excel VBA projects: source files, JSON output, explicit exit codes, diagnostics, sessions, and visual inspection commands.

Every command can return a stable JSON envelope, so coding agents can parse results without scraping terminal text. See JSON Output and Error Codes.

Before editing, confirm workbook and source state:

xlflow status --json

Recommended loop:

xlflow doctor --json
xlflow status --json
xlflow session start --json
xlflow pull --session --json
xlflow push --fast --session --no-save --json
xlflow lint --json
xlflow analyze --json
xlflow test --session --json
xlflow macros --session --json
xlflow run Main.Run --headless --session --json
xlflow save --session --json

When the agent runs inside WSL, keep the repository under /mnt/<drive>/... and install xlflow on both WSL and Windows. The same commands transparently delegate Excel operations to Windows while lint, fmt, and analyze remain in WSL. Prefer the session-first sequence:

xlflow doctor --json
xlflow session start --json
xlflow push --fast --session --no-save --json
xlflow run Main.Run --diagnostic --session --json
xlflow inspect workbook --session --json
xlflow save --session --json
xlflow session stop --json

If a run fails, check state and recover with a short loop:

xlflow status --json
xlflow lint --json
xlflow analyze --json
xlflow run Main.Run --diagnostic --session --json
xlflow inspect workbook --json
xlflow pull --session --json

Use run --diagnostic when you need structured compile or runtime failure details instead of a blind Excel/VBE dialog. Re-run pull after workbook-side investigation when you need the latest saved workbook state back in source.

Recovery-required workflow

If a result contains error.code: "workbook_recovery_required" or top-level recovery.required: true, stop the normal loop. Do not retry with --wait and do not save the quarantined session.

xlflow status --json
xlflow session stop --discard --json
# or, when an affected PID is reported:
xlflow process cleanup <pid> --json
xlflow recovery clear --json
xlflow status --json

For external user-owned Excel sessions, do not close or discard the workbook automatically. Ask the user to close it without saving, then run verified recovery clear. Use recovery clear --force only with explicit acceptance that it clears the marker without stopping VBA or proving workbook safety.

Install the bundled skill when supported by your agent:

xlflow skill install --agent codex