aidermacs

When aidermacs-watch-files is enabled, Aidermacs watches your repository for specific comment-based instructions. This feature currently requires the vterm backend.

Instruction Syntax: Use one-liner comments that start or end with AI, AI!, or AI?:

• # Instruction AI!: Triggers Aider to make changes to the code.
• # Question AI?: Triggers Aider to answer the question.
• # Instruction AI: General instruction.

;; Enable file watching
(setq aidermacs-watch-files t)

While Aidermacs integrates with the Aider CLI, it is designed as an Emacs-native experience rather than a CLI mirror. Key features include:

• Ediff Integration: Automatically uses Emacs' ediff for seamless code review and diffing of AI-generated changes.
• Multiline Input: Handles complex, multiline prompts natively within Emacs, bypassing terminal limitations.
• Terminal Backends: Supports both comint and vterm backends.
• File Management: Provides specialized Emacs commands for adding/dropping files and managing sessions.
• Model Selection: Features intelligent, real-time model discovery and compatibility checking.

Aidermacs follows a strict hierarchy to determine settings.

1. Highest Priority: Aider Configuration File (.aider.conf.yml) If a config file is found, Aidermacs ignores its own Emacs variables (like aidermacs-default-model). You should define all settings in the .aider.conf.yml to avoid conflicts.

2. Second Priority: Emacs Configuration (if no .aider.conf.yml is used) If no config file is present, settings are applied in this order:

• Emacs Variables (e.g., setq aidermacs-default-model)
• Environment Variables (e.g., AIDER_MODEL)
• Built-in Defaults

Effective AI interaction requires managing which files the AI can see and edit.

File Access Modes

• Editable Files: Add files normally to allow the AI to both read and modify them.
• Read-Only Files: To allow the AI to read a file without permission to edit it, prefix any 'Add File' command with C-u.
• Session Scratchpads: Use the S command in the transient menu to create scratchpads. These are useful for pasting notes or documentation that the AI can use as read-only context.
• External Files: Use the G (Add File to Session) command to include files that are outside the current project root or are listed in .gitignore.

Best Practices

While the AI may infer context, manually specifying files (especially in complex projects) provides more precise control over the AI's scope.

In solo (non-Architect) mode, Aidermacs can automatically discover and fetch available models from providers like OpenAI, Anthropic, DeepSeek, Google Gemini, and OpenRouter. It caches these lists and handles authentication via your .bashrc keys.

To change models during a session:

1. Run M-x aidermacs-change-model or press o in the transient menu.
2. Choose between pre-configured models or dynamically fetched models.

Aider currently only supports Python 3.12. If you are using Python 3.13, it is recommended to use uv to install a specific Python 3.12 version of aider-chat to avoid compatibility issues.

uv tool install --force --python python3.12 aider-chat@latest

For Spacemacs users, add aidermacs to your dotspacemacs-additional-packages and set your preferred keybindings in dotspacemacs/user-config.

1. Add Package

dotspacemacs-additional-packages '((
  aidermacs :variables
              aidermacs-default-chat-mode 'architect
              aidermacs-default-model "sonnet")
))

2. Set Keybindings

(defun dotspacemacs/user-config ()
  ;; Example: bind to SPC a a
  (spacemacs/set-leader-keys "aa" 'aidermacs-transient-menu)
)

Aidermacs supports remote files through Emacs' Tramp mode (SSH, Docker, etc.). When you open a remote file, Aidermacs automatically detects the remote context, localizes file paths, and applies edits directly to the remote system.

;; Open a remote file via SSH
(find-file "/ssh:user@remotehost:/path/to/file.py")

;; Start Aidermacs session
M-x aidermacs-transient-menu

Aidermacs includes a minor mode specifically for working with Aider-related files like .aider.prompt.org, .aider.chat.md, .aider.chat.history.md, and .aider.input.history.

When this mode is active, use the following keybindings:

• C-c C-n or C-<return>: Send line/region line-by-line
• C-c C-c: Send block/region as a whole
• C-c C-z: Switch to the Aidermacs buffer

To create a new prompt file, use M-x aidermacs-open-prompt-file.