<p align="center"> <img style='height: auto; width: 40%; object-fit: contain' src="./aidermacs.png"> </p>

Aidermacs: AI Pair Programming in Emacs

Aidermacs brings AI-powered development to Emacs by integrating Aider, one of the most powerful open-source AI pair programming tools. If you're missing Cursor but prefer living in Emacs, Aidermacs provides similar AI capabilities while staying true to Emacs workflows.

<img style='height: auto; width: 80%; object-fit: contain' src="./introscreen.png">

Key Features

• Intelligent model selection with multiple backends
• Built-in Ediff integration for AI-generated changes
• Enhanced file management from Emacs
• Great customizability and flexible ways to add content

Community Speaks

Here's what the community is saying about Aidermacs:

"Are you using aidermacs? For me superior to cursor." - u/berenddeboer

"This is amazing... every time I upgrade my packages I see your new commits. I feel this the authentic aider for emacs" - u/wchmbo

"Between Aidermacs and Gptel it's wild how bleeding edge Emacs is with this stuff. My workplace is exploring MCP registries and even clients that are all the rage (E.g Cursor) lag behind what I can do with mcp.el and gptel for tool use." - u/no_good_names_avail

"This looks amazing... I have been using ellama with local llms, looks like that will work here too. Great stuff!!" - u/lugpocalypse

"Honestly huge fan of this. Thank you for the updates!" - u/ieoa

Quick Start

1. Requirements

• Emacs ≥ 26.1
• Aider or its community fork Aider Community Experimentation.
• Transient

2. Download Aidermacs through Melpa or Non-GNU Elpa, or clone manually
3. Modify this sample config and place it in your Emacs init.el:

(use-package aidermacs
  :bind (("C-c a" . aidermacs-transient-menu))
  :config
  ; Set API_KEY in .bashrc, that will automatically picked up by aider or in elisp
  (setenv "ANTHROPIC_API_KEY" "sk-...")
  ; defun my-get-openrouter-api-key yourself elsewhere for security reasons
  (setenv "OPENROUTER_API_KEY" (my-get-openrouter-api-key))
  :custom
  ; See the Configuration section below
  (aidermacs-default-chat-mode 'architect)
  (aidermacs-default-model "sonnet"))

4. Open a project and run M-x aidermacs-transient-menu or SPC a a (or your chosen binding).
5. Add files and start coding with AI!

Spacemacs

For Spacemacs users:

1. Add aidermacs to your dotspacemacs-additional-packages list in your .spacemacs file:

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

2. Add the keybinding to your dotspacemacs/user-config function in .spacemacs:

(defun dotspacemacs/user-config ()
  ;; Set leader key for Aidermacs
  (spacemacs/set-leader-keys "aa" 'aidermacs-transient-menu) ; Example binding SPC a a
)

3. Open a project and run M-x aidermacs-transient-menu or SPC a a (or your chosen binding).
4. Add files and start coding with AI!

Usage

Getting Started

The main interface to Aidermacs is through its transient menu system (similar to Magit). Access it with:

M-x aidermacs-transient-menu

Or bind it to a key in your config:

(global-set-key (kbd "C-c a") 'aidermacs-transient-menu)

Once the transient menu is open, you can navigate and execute commands using the displayed keys. Here's a summary of the main menu structure:

Core

• a: Start/Open Session (auto-detects project root)
• .: Start in Current Directory (good for monorepos)
• l: Clear Chat History
• s: Reset Session
• x: Exit Session

Persistent Modes

• 1: Code Mode
• 2: Chat/Ask Mode
• 3: Architect Mode
• 4: Help Mode

Utilities

• ^: Show Last Commit (if auto-commits enabled)
• u: Undo Last Commit (if auto-commits enabled)
• R: Refresh Repo Map
• h: Session History
• o: Change Main Model
• v: Send Voice Command
• W: Fetch Web Content
• ?: Aider Meta-level Help

File Actions

• f: Add File (C-u: read-only)
• F: Add Current File
• d: Add From Directory (same type)
• w: Add From Window
• m: Add From Dired (marked)
• j: Drop File
• J: Drop Current File
• k: Drop From Dired (marked)
• K: Drop All Files
• S: Create Session Scratchpad
• G: Add File to Session
• A: List Added Files

Code Actions

• c: Code Change
• e: Question Code
• r: Architect Change
• q: General Question
• p: Question This Symbol
• g: Accept Proposed Changes
• i: Implement TODO
• t: Write Test
• T: Fix Test
• !: Debug Exception

The All File Actions and All Code Actions entries open submenus with more specialized commands. Use the displayed keys to navigate these submenus.

File Management and AI Interaction

When using Aidermacs, you have the flexibility to decide which files the AI should read and edit. Here are some guidelines:

• Editable Files: Add files you want the AI to potentially edit. This grants the AI permission to both read and modify these files if necessary.
• Read-Only Files: If you want the AI to read a file without editing it, you can add it as read-only. In Aidermacs, all add file commands can be prefixed with C-u to specify read-only access.
• Session Scratchpads: Use the session scratchpads (S) to paste notes or documentation that will be fed to the AI as read-only.
• External Files: The "Add file to session" (G) command allows you to include files outside the current project (or files in .gitignore), as Aider doesn't automatically include these files in its context.

The AI can sometimes determine relevant files on its own, depending on the model and the context of the codebase. However, for precise control, it's often beneficial to manually specify files, especially when dealing with complex projects.

Aider encourages a collaborative approach, similar to working with a human co-worker. Sometimes the AI will need explicit guidance, while other times it can infer the necessary context on its own.

Prompt Files Minor Mode

Aidermacs provides a minor mode that makes it easy to work with prompt files and other Aider-related files. When enabled, the minor mode provides these convenient keybindings:

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

The minor mode is automatically enabled for:

• .aider.prompt.org files (create with M-x aidermacs-open-prompt-file)
• .aider.chat.md files
• .aider.chat.history.md files
• .aider.input.history files

Configuration

Pre-Run Hook

You can use the aidermacs-before-run-backend-hook to run custom setup code before starting the Aider backend. This is particularly useful for:

• Setting environment variables
• Injecting secrets
• Performing any other pre-run configuration

Example usage to securely set an OpenAI API key from password-store:

(add-hook 'aidermacs-before-run-backend-hook
          (lambda ()
            (setenv "OPENAI_API_KEY" (password-store-get "code/openai_api_key"))))

An copy of process-environment is used when running the hook and starting Aider, ensuring environment variables set in the hook only affect the Aider backend. This approach keeps sensitive information out of your dotfiles while still making it available to Aidermacs.

Default Model Selection

You can customize the default AI model used by Aidermacs. The model is determined in the following order of priority:

1. The value of the Emacs variable aidermacs-default-model if you have set it (e.g., via setq).
2. The value of the AIDER_MODEL environment variable, if set.
3. A built-in default value (e.g., "sonnet").

To set it in Emacs:

(setq aidermacs-default-model "sonnet")

This enables easy switching between different AI models without modifying the aidermacs-extra-args variable.

Note: This configuration will be overwritten by the existence of an .aider.conf.yml file (see details).

Dynamic Model Selection

Aidermacs offers intelligent model selection for solo (non-Architect) mode, automatically detecting and integrating with multiple AI providers:

• Automatically fetches available models from supported providers (OpenAI, Anthropic, DeepSeek, Google Gemini, OpenRouter)
• Caches model lists for quick access
• Supports both popular pre-configured models and dynamically discovered ones
• Handles API keys and authentication automatically from your .bashrc
• Provides model compatibility checking

The dynamic model selection is only for the solo (non-Architect) mode.

To change models in solo mode:

1. Use M-x aidermacs-change-model or press o in the transient menu
2. Select from either:
   • Popular pre-configured models (fast)
   • Dynamically fetched models from all supported providers (comprehensive)

The system will automatically filter models to only show ones that are:

• Supported by your current Aider version
• Available through your configured API keys
• Compatible with your current workflow

Architect Mode - Separating Code Reasoning and Editing Models

Aidermacs features an experimental mode using two specialized models for each coding task: an Architect model for reasoning and an Editor model for code generation. This approach has achieved state-of-the-art (SOTA) results on aider's code editing benchmark, as detailed in this blog post.

To start new sessions in Architect mode by default, set aidermacs-default-chat-mode to 'architect.

aidermacs-use-architect-mode is deprecated and will be removed in a future release.

architect mode will default to using aidermacs-default-model. You may also configure the aidermacs-architect-model variable to specify the model to use for the Architect role if you prefer a different main model when using architect mode.

By default, the aidermacs-editor-model is the same as aidermacs-default-model. You only need to set aidermacs-editor-model if you want to use a different model for the Editor role. This variable also respects the AIDER_EDITOR_MODEL environment variable, following the same priority as aidermacs-default-model.

(setq aidermacs-default-chat-mode 'architect)

You can switch to it persistently by M-x aidermacs-switch-to-architect-mode (3 in aidermacs-transient-menu), or temporarily with M-x aidermacs-architect-this-code (r in aidermacs-transient-menu).

You can configure each model independently:

;; Default model used for all modes unless overridden
(setq aidermacs-default-model "sonnet")

;; Optional: Set specific mode