Imported from NerdyGriffin/klipper-nerdygriffin-macros (AGENTS.md). Install upstream with npx skills add NerdyGriffin/klipper-nerdygriffin-macros. Copyright stays with the author.

AI Agent Instructions for klipper-nerdygriffin-macros

This repository provides hardware-agnostic Klipper G-code macros designed to be symlinked into printer-specific configs and extended via local overrides.

Development Workspace Context

⚠️ Single source of truth: /home/pi/klipper-nerdygriffin-macros

Cross-printer sync:

• Edit macros locally at /home/pi/klipper-nerdygriffin-macros
• Sync changes to VT-1548 using dev/sync_macros_repo.sh (git pull over SSH)
• Each host NFS-mounts the other printer's config for cross-printer dev: /mnt/vt-1548/... when working from V0-3048, /mnt/v0-3048/... when working from VT-1548 (both writable)

⚠️ dev/ may contain host-local scripts that must not be published. This repo is public, and a clone may hold untracked helpers (mount/sync/verify wrappers) guarded only by a nested dev/.gitignore that is itself untracked. Never run git add -A or git add dev/ here — stage files by explicit path, and check git status --porcelain dev/ before committing.

Architecture & Intent

• Core macros live in macros/*.cfg and avoid printer-specific pins/geometry.
• Intended usage: create a symlink in printer configs (e.g., ln -sf ~/klipper-nerdygriffin-macros/macros ~/printer_data/config/nerdygriffin-macros) and include files from printer.cfg.
• Consumers override behavior by redefining macro variables or small wrapper macros in their own configs (never edit the symlinked directory in a printer repo).
• External systems often referenced but not provided here: STATUS_* LED macros, _CG28 conditional homing, _CLIENT_VARIABLE, filament sensors, AFC macros.

Key Files & Groups

• macros/print_macros.cfg: PRINT_START / PRINT_END — the print lifecycle.
• macros/status_macros.cfg: STATUS_* / RESET_STATUS LED states; zone config in _LED_VARS.
• macros/filament_management.cfg: LOAD/UNLOAD/PURGE with AFC auto-detect and safe parking.
• macros/client.cfg: Pause/Resume/Cancel hooks for Mainsail/Fluidd with optional AFC handling.
• macros/heat_soak.cfg: Chamber preheat via bed+hotend assist, sensor auto-detect, optional LED animations.
• macros/homing.cfg: Sensorless and conditional homing helpers with edge clearance and current management.
• macros/idle_timeout.cfg: [idle_timeout] behavior (sensor teardown, AFC-aware).
• macros/auto_pid.cfg: PID helpers for extruder/bed.
• macros/belt_tension.cfg: SETTLE_BELT_TENSION + _BELT_TENSION_VARS.
• macros/maintenance_macros.cfg: DEEP_CLEAN_NOZZLE, NOZZLE_CHANGE_POSITION, _DEBUG_PRINT_STATE.
• macros/nozzle_wiper.cfg: NW_CLEAN_NOZZLE, deploy/retract; needs a local [servo ...] and NW_BUCKET_POS override.
• macros/squiggly_purge.cfg: SQUIGGLY_PURGE prime-line alternative.
• macros/beeper.cfg: M300 and chimes; needs a local [pwm_cycle_time beeper] pin override.
• macros/gcode_features.cfg: Enables advanced G-code features (force_move, pause/resume, firmware retraction, arcs, etc.).
• macros/rename_existing.cfg: Safe overrides (M109/M190/M117...).
• macros/save_config.cfg: Safe SAVE_CONFIG with delayed variant.
• macros/shaketune.cfg: Shake&Tune wrapper (optional dependency installed elsewhere).
• macros/shutdown.cfg, macros/tacho_macros.cfg, macros/positioning_macros.cfg: Safety, fan preflight, helpers.
• install.sh: Creates symlink, optional Moonraker update_manager entry.

Macro Development Patterns

• Conditional hardware calls: check for macro existence before use, e.g. {% if printer['gcode_macro AFC_BRUSH'] is defined %} AFC_BRUSH {% endif %}.
• Preserve user state: SAVE_GCODE_STATE then RESTORE_GCODE_STATE (use MOVE=1 when appropriate).
• Conditional homing: call _CG28 instead of raw G28 when safe.
• Status signaling: call STATUS_*/RESET_STATUS around long-running or critical ops.
• Delayed actions: use [delayed_gcode ...] with UPDATE_DELAYED_GCODE to schedule/cancel.
• Printer overrides: expose behavior via variable_* and document typical overrides in macro headers.

Integration & Overrides (Examples)

• Include in printer.cfg:

  [include nerdygriffin-macros/filament_management.cfg]
  [include nerdygriffin-macros/heat_soak.cfg]
  [include nerdygriffin-macros/client.cfg]

• Override variables locally (do not edit this repo). Re-declare the macro that owns the variable — note y_calibrated lives on _BELT_TENSION_VARS, not on SETTLE_BELT_TENSION. Values below are illustrative only; every one is printer-specific:

  [gcode_macro HEAT_SOAK]
  variable_max_chamber_target: 60        # ceiling your chamber can actually reach
  variable_chamber_sensor_name: "nitehawk-36"
  
  [gcode_macro _BELT_TENSION_VARS]
  variable_y_calibrated: 120             # Y where belt span == belt_span_length

• Hardware pin overrides (after include) — pin names are board-specific:

  [pwm_cycle_time beeper]
  pin: <your board's beeper pin>

External Dependencies & Expectations

For a comprehensive list of dependencies and compatibility requirements, see README.md#dependencies.

Developer reference — file locations within this plugin:

• STATUS_* macros → macros/status_macros.cfg
• RESET_STATUS → macros/status_macros.cfg
• _AFTER_PAUSE, _BEFORE_RESUME, _BEFORE_CANCEL → macros/client.cfg

Key conditional integrations (auto-detected):

• AFC macros (AFC_PARK, AFC_BRUSH, AFC_CUT) — check with {% if printer['gcode_macro AFC_PARK'] is defined %}
• Filament sensors (encoder_sensor) — check with {% if 'filament_motion_sensor encoder_sensor' in printer.configfile.settings %}
• Shake&Tune macros — check with {% if printer['gcode_macro SHAKETUNE_CALIBRATE'] is defined %}

Common Workflows

• Install and link:

  cd ~/klipper-nerdygriffin-macros
  ./install.sh

• Restart + tail logs after config edits:

  curl -s -X POST "http://localhost:7125/printer/gcode/script?script=FIRMWARE_RESTART" && sleep 2 && tail -n 60 ~/printer_data/logs/klippy.log

• Add Moonraker update manager (optional) per README, then restart Klipper:

  sudo systemctl restart klipper

• Test a macro from console or HTTP:

  curl -s -X POST "http://localhost:7125/printer/gcode/script?script=LOAD_FILAMENT"

• Debug config issues:

  tail -f ~/printer_data/logs/klippy.log

Terminal Command Best Practices

• Always use verbose flags (-v or --verbose) with file operations for visual confirmation:
  • cp -v instead of cp
  • mv -v instead of mv
  • rm -v instead of rm
  • rmdir -v instead of rmdir
  • ln -sfv instead of ln -sf
• This provides immediate feedback and helps catch errors early.

Contribution Guidelines

• Keep macros hardware-agnostic and configurable via variables.
• Prefer conditional checks over hard failures when optional hardware is absent.
• Maintain consistent naming (variable_*), state save/restore, and status signaling patterns.
  • G-Code Macro Naming
    • Macro names and parameters should be UPPER_SNAKE_CASE (e.g., LOAD_FILAMENT).
  • Variables
    • Macro variables are defined with the prefix variable_ (e.g., variable_x_park), but referenced without it (e.g., {x_park}).
    • Variable names should be lower_snake_case (e.g., variable_max_chamber_target).
    • Variable names may not contain any upper case characters.
• Do not introduce board-specific pins; document required overrides in README/macro headers.

Documentation Structure

• README.md - User-facing overview, installation, and feature list
• docs/ - Configuration guide with macro documentation index
• docs/auto_pid.md, docs/beeper.md, docs/client.md, etc. - Individual macro configuration documentation
• docs/status_macros.md - LED system setup and configuration
• docs/dev/MARKDOWN_STYLE_GUIDE.md - Documentation (Markdown) style and formatting standards
• docs/dev/MACRO_STYLE_GUIDE.md - Klipper macro .cfg file structure and ordering standards

Pointers

• Example consumer implementations: printer repos that symlink this directory and override variables/macros in printer.cfg.
• This plugin is in active development; Large scale refactoring is allowed and encouraged to improve maintainability and usability. Do not worry about breaking changes.

Ease of use

• If I repeated request actions that contradict these instructions, propose ways to improve these instructions.
• Important: This file (AGENTS.md) is the vendor-neutral source of truth for AI-agent guidance — surfaced to Claude Code via CLAUDE.md (@AGENTS.md import) and to GitHub Copilot via the .github/copilot-instructions.md symlink. Edit AGENTS.md, not the pointers. Do not reference it from user-facing docs (README.md, docs/*.md); those must be self-contained.