aidermacs: Aider AI Pair Programming for Emacs

Introduction

Miss using Cursor but prefer working in Emacs? Aidermacs brings Cursor-like AI-powered development to your Emacs workflow by integrating Aider, one of the most powerful open-source AI pair programming tools available. As a community-driven project, Aidermacs prioritizes the needs and preferences of Emacs users. It provides the same powerful features you’d find in Cursor:

• Top performance on the SWE Bench, solving real GitHub issues in major open source projects
• Seamless Git integration with automatic, sensible commit messages
• Support for multi-file edits in complex codebases
• Real-time file synchronization for true pair programming
• Broad language support including Python, JavaScript, TypeScript, PHP, HTML, CSS, and more
• Compatibility with leading AI models like Claude 3.5 Sonnet, DeepSeek, and GPT-4o

Community-Driven Development

Aidermacs thrives on community involvement. We believe that the best software is built collaboratively, with input from users and contributors. We encourage you to:

• Contribute Code: Submit pull requests with bug fixes, new features, or improvements to existing functionality.
• Report Issues: Let us know about any bugs, unexpected behavior, or feature requests through GitHub Issues.
• Share Ideas: Participate in discussions and propose new ideas for making Aidermacs even better.
• Improve Documentation: Help us make the documentation clearer, more comprehensive, and easier to use.

Your contributions are essential to making Aidermacs the best AI pair programming tool for Emacs!

Why aidermacs over aider.el?

Aidermacs begins as a fork of aider.el, created to offer a more Emacs-native experience while still integrating with Aider.

While aider.el strictly mirrors Aider’s CLI behavior, aidermacs prioritizes Emacs workflow integration. This design philosophy allows you to harness Aider’s powerful capabilities through a natural, Emacs-native coding experience.

With aidermacs, you get:

1. Better Support for Multiline Input
   • aider is primarily designed as a command-line program, where multiline input is restricted by terminal limitations.
   • Terminal-based tools require special syntax or manual formatting to handle multiline input, which can be cumbersome and unintuitive.
   • aidermacs eliminates these restrictions by handling multiline prompts natively within Emacs, allowing you to compose complex AI requests just like any other text input.
   • Whether you’re pasting blocks of code or refining AI-generated responses, multiline interactions in aidermacs feel natural and seamless.
2. Smarter Syntax Highlighting
   • AI-generated code appears with proper syntax highlighting in major languages.
   • Ensures clarity and readability without additional configuration.
3. Flexible Terminal Backend Support
   • aidermacs supports multiple terminal backends (comint and vterm) for better compatibility and performance
   • Easy configuration to choose your preferred terminal emulation
   • Extensible architecture for adding new backends
4. Community-Focused Development
   • aidermacs is actively developed and maintained by the community, incorporating user feedback and contributions.
   • We prioritize features and improvements that directly benefit Emacs users, ensuring a tool that evolves with your needs.

… and more to come 🚀

Installation

Requirements

• Emacs ≥ 26.1
• Aider
• Transient

Sample Config With Straight

(use-package aidermacs
  :straight (:host github :repo "MatthewZMD/aidermacs" :files ("*.el"))
  :config
  (setq aidermacs-args '("--model" "anthropic/claude-3-5-sonnet-20241022"))
  (setenv "ANTHROPIC_API_KEY" anthropic-api-key)
  (global-set-key (kbd "C-c a") 'aidermacs-transient-menu))

Sample Config With Doom Emacs

(package! aidermacs :recipe (:host github :repo "MatthewZMD/aidermacs" :files ("*.el")))

Configuration

Terminal Backend Selection

Choose your preferred terminal backend by setting aidermacs-backend:

vterm provides better terminal compatibility and bracketed paste support, while comint is a simpler, built-in option.

;; Use vterm backend (default is comint)
(setq aidermacs-backend 'vterm)

Available backends:

• comint (default): Uses Emacs’ built-in terminal emulation
• vterm: Leverages vterm for better terminal compatibility

Multiline Input Configuration

When using the comint backend, you can customize the key binding for multiline input:

;; Change multiline input key (default is S-<return>)
(setq aidermacs-comint-multiline-newline-key "C-<return>")

This key allows you to enter multiple lines without sending the command to Aider. Press RET normally to send the command.

Usage

This section provides a step-by-step guide on how to use Aidermacs for AI-assisted pair programming in Emacs.

1. Start an Aidermacs Session

• Use the command M-x aidermacs-run-aidermacs (a in transient menu) to start an Aidermacs session.
• This will open a new buffer named *aidermacs:your-repo-name* where you can interact with the AI.
• If you want to use a specific AI model, you can customize the aidermacs-args variable in your Emacs configuration.
• You can also select a model interactively by using M-x aidermacs-change-model (o in transient menu).

2. Add Files to the Session

To provide context to the AI, you need to add relevant files to the Aidermacs session:

• Add current file: M-x aidermacs-add-current-file (f in transient menu)
• Add current file in read-only mode: M-x aidermacs-current-file-read-only (R in transient menu)
• Add all files in current window: M-x aidermacs-add-files-in-current-window (w in transient menu)
• Add all files with same suffix in current directory: M-x aidermacs-add-same-type-files-under-dir (d in transient menu)
• In dired-mode, add marked files: M-x aidermacs-batch-add-dired-marked-files (b in transient menu)

3. Interact with the AI

After adding files to the session, switch to the *aidermacs* buffer to interact with the AI using these commands:

Code Changes

• Request code changes: M-x aidermacs-code-change (c in transient menu)
• Refactor function/region: M-x aidermacs-function-or-region-refactor (r in transient menu)
• Implement TODO comments: M-x aidermacs-implement-todo (i in transient menu)
• Start architectural discussion: M-x aidermacs-architect-discussion (t in transient menu)
• Undo last AI change: M-x aidermacs-undo-last-change (u in transient menu)

Questions and Explanations

• Ask the AI questions about the current code context: M-x aidermacs-ask-question (q in transient menu)
• Ask the AI a general question: M-x aidermacs-general-question (Q in transient menu)
• Explain a function or region of code: M-x aidermacs-function-or-region-explain (e in transient menu)
• Explain the symbol at point: M-x aidermacs-explain-symbol-under-point (p in transient menu)
• Get help on aidermacs commands: M-x aidermacs-help (h in transient menu)

Testing and Debugging

• Generate unit tests: M-x aidermacs-write-unit-test (U in transient menu)
• Fix failing test: M-x aidermacs-fix-failing-test-under-cursor (T in transient menu)
• Debug exception: M-x aidermacs-debug-exception (D in transient menu)

Other Interactions

• Continue with last task: M-x aidermacs-go-ahead (y in transient menu)
• General command: M-x aidermacs-general-command (g in transient menu)
• Show last commit with Magit: M-x aidermacs-magit-show-last-commit (m in transient menu)

4. Send Code Blocks

When working with code blocks, you can use these commands:

• Send line or region line-by-line: C-c C-n or C-<return>
• Send block/region as whole: C-c C-c

These keybindings are available in the minor mode.

5. Manage the Aidermacs Session

Session management commands:

• Switch to Aidermacs buffer: C-c C-z or M-x aidermacs-switch-to-buffer (z in transient menu)
• Clear buffer: M-x aidermacs-clear (l in transient menu)
• Reset session: M-x aidermacs-reset (s in transient menu)
• Exit session: M-x aidermacs-exit (x in transient menu)

6. Prompt Files

• Open/create prompt file: M-x aidermacs-open-prompt-file (p in transient menu)
• The prompt file (.aider.prompt.org) is created in your Git repository root
• Use it to store frequently used prompts
• When the prompt file is open, you can use these keybindings:
  • C-c C-n or C-<return>: Send current line/region line-by-line
  • C-c C-c: Send current block/region as whole
  • C-c C-z: Switch to Aidermacs buffer

7. Transient Menu

• Access all commands through the transient menu: M-x aidermacs-transient-menu
• The transient menu is a popup menu that provides a convenient way to access all aidermacs commands.
• The menu groups commands into categories:
  • “aidermacs Process”: Basic session management (a, z, o, l, s, x)
  • “Add File to aidermacs”: File management (f, R, w, d, b)
  • “Code Change”: Code modifications (t, c, r, i, U, T, m, u)
  • “Discussion”: Questions and explanations (q, y, e, p, D)
  • “Other”: Additional commands (g, Q, p, h)
• Toggle options are available at the top of some sections

Note: The default keybindings in the minor mode map (C-c C-n, C-<return>, C-c C-c, and C-c C-z) are always available when the minor mode is active. All other commands can be accessed either through M-x or through the transient menu after invoking M-x aidermacs-transient-menu.