branch: elpa/aidermacs
commit f83fb13a0fa4d4dfbb24b5dbe21a3943d2baa5ba
Author: Mingde (Matthew) Zeng <matthew...@posteo.net>
Commit: Mingde (Matthew) Zeng <matthew...@posteo.net>
Introduce Aidermacs
Signed-off-by: Mingde (Matthew) Zeng <matthew...@posteo.net>
---
README.org | 258 +++++++++++++++++--------------------------------------------
1 file changed, 73 insertions(+), 185 deletions(-)
diff --git a/README.org b/README.org
index dee6ab39ef..b49691a84d 100644
--- a/README.org
+++ b/README.org
@@ -1,225 +1,113 @@
-#+TITLE: aider.el : aider (AI Pair Programming) Inside Emacs
+#+TITLE: aidermacs : Aider AI Pair Programming for Emacs
+#+OPTIONS: toc:2
* Introduction
-- Do you enjoy the AI features of the [[https://www.cursor.com/][Cursor AI
Code Editor]] but prefer working within Emacs?
+Miss using [[https://cursor.sh][Cursor]] but prefer working in Emacs?
Aidermacs brings Cursor-like AI-powered development to your Emacs workflow by
integrating [[https://github.com/paul-gauthier/aider][Aider]], one of the most
powerful **open-source** AI pair programming tools available. Aidermacs
provides the same powerful features you'd find in Cursor:
-- [[https://github.com/paul-gauthier/aider][Aider]] is a well-known and highly
effective AI pair programming tool for the terminal.
+- 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
-- The `aider.el` package offers an interactive interface to communicate with
Aider in Emacs.
- - Most of the Elisp code in this repository was generated by Aider or
`aider.el`.
-* Benefits: UI, User-friendly UI, Context Awareness, AI-Assisted Code
Development
-- Pop-up Menu: No need to remember commands. (aider-transient-menu)
+* Why aidermacs over aider.el?
+Aidermacs begins as a fork of
[[https://github.com/tninja/aider.el][aider.el]], created to offer a more
Emacs-native experience while still integrating with
[[https://github.com/paul-gauthier/aider][Aider]], a powerful AI pair
programming tool.
-[[file:./transient_menu.png]]
+While =aider.el= strictly mirrors Aider's CLI behavior, =aidermacs=
prioritizes Emacs usability and native workflow integration. This design
philosophy allows you to harness Aider's powerful capabilities through a
natural, Emacs-native coding experience.
-- Work directly on the code without switching contexts — each file is
automatically linked to a Git repository-specific Aider session.
+With =aidermacs=, you get:
-- Pass your Emacs editing context to Aider, including details such as the
active function or class and any selected code. This minimizes manual typing.
+1. Better Support for Multiline Input
+ - =aider= is primarily designed as a command-line program, where multi-line
input is restricted by terminal limitations.
+ - Terminal-based tools require special syntax or manual formatting to
handle multi-line input, which can be cumbersome and unintuitive.
+ - =aidermacs= **eliminates these restrictions** by handling multi-line
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**.
-- Designed for everyday programming tasks, such as adding or modifying code
with AI assistance, verifying the accuracy of AI-generated code, and reviewing
code written by others.
+2. Smarter Syntax Highlighting
+ - AI-generated code **appears with proper syntax highlighting** in major
languages.
+ - Ensures clarity and readability without additional configuration.
-* Installation
+... and more to come 🚀
-- Emacs need to be >= 26.1
+* Installation
-** Vanilla Emacs Installation
-- [[https://aider.chat/docs/install.html][Install aider]]
-- Install the emacs dependency library
[[https://github.com/magit/transient][Transient]], and
[[https://github.com/magit/magit][Magit]] using your package manager.
-- Install aider.el with the following code:
+** Requirements
+- Emacs ≥ 26.1
+- [[https://aider.chat/docs/install.html][Aider]]
+- [[https://github.com/magit/transient][Transient]] and
[[https://github.com/magit/magit][Magit]]
-*** With
[[https://github.com/radian-software/straight.el?tab=readme-ov-file][Straight]]
-If you have Straight installed
+** With Straight
#+BEGIN_SRC emacs-lisp
- (use-package aider
- :straight (:host github :repo "tninja/aider.el" :files ("aider.el"))
- :config
- ;; Use claude-3-5-sonnet cause it is best in aider benchmark
- (setq aider-args '("--model" "anthropic/claude-3-5-sonnet-20241022"))
- (setenv "ANTHROPIC_API_KEY" anthropic-api-key)
- ;; Or use chatgpt model since it is most well known
- ;; (setq aider-args '("--model" "o3-mini"))
- ;; (setenv "OPENAI_API_KEY" <your-openai-api-key>)
- ;; Or use gemini v2 model since it is very good and free
- ;; (setq aider-args '("--model" "gemini/gemini-exp-1206"))
- ;; (setenv "GEMINI_API_KEY" <your-gemini-api-key>)
- ;; Or use your personal config file
- ;; (setq aider-args `("--config" ,(expand-file-name "~/.aider.conf.yml")))
- ;; ;;
- ;; Optional: Set a key binding for the transient menu
- (global-set-key (kbd "C-c a") 'aider-transient-menu))
+(use-package aidermacs
+ :straight (:host github :repo "MatthewZMD/aidermacs" :files ("aider.el"))
+ :config
+ (setq aider-args '("--model" "anthropic/claude-3-5-sonnet-20241022"))
+ (setenv "ANTHROPIC_API_KEY" anthropic-api-key)
+ (global-set-key (kbd "C-c a") 'aider-transient-menu))
#+END_SRC
-*** With
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Fetching-Package-Sources.html#:~:text=One%20way%20to%20do%20this,just%20like%20any%20other%20package.][package-vc-install]]
(emacs built-in)
-- Install Aider.el by running the following code within Emacs
- - You'll need to manually install the required packages, such as
[[https://github.com/magit/transient][Transient]],
[[https://github.com/magit/magit][Magit]], and helm.
+** With package-vc-install
#+BEGIN_SRC emacs-lisp
-(package-vc-install '(aider :url "https://github.com/tninja/aider.el";))
+(package-vc-install '(aider :url "https://github.com/MatthewZMD/aidermacs";))
#+END_SRC
-The config part is as same as above straight one
-
-** Doom Installation and Configuration
-
-- Add the following code to your doom/packages.el
-
+** For Doom Emacs
+In =packages.el=:
#+BEGIN_SRC emacs-lisp
-(package! aider :recipe (:host github :repo "tninja/aider.el" :files
("aider.el" "aider-doom.el")))
+(package! aider :recipe (:host github :repo "MatthewZMD/aidermacs" :files
("aider.el" "aider-doom.el")))
#+END_SRC
-- Adjust and add the following code to your doom/config.el
-
+In =config.el=:
#+BEGIN_SRC emacs-lisp
(use-package aider
:config
(setq aider-args '("--model" "o3-mini")))
#+END_SRC
-The aider prefix is "A".
-
-- Start and open the aider buffer: =[SPC] A o=
-- Add the current file with =[SPC] A a c=
-- Reset the aider session with =[SPC] A r=
-[[file:./doom-menus.png]]
+* Core Features
-** Optional
+** Session Management
+- Create repository-specific Aider sessions
+- Switch between multiple AI sessions
+- Toggle between window and frame views
-*** Helm Support
+** Code Operations
+- Add files in read-write or read-only mode
+- Refactor selected regions or functions
+- Implement TODOs from comments
+- Generate and fix unit tests
+- Analyze and explain code
-Helm enables fuzzy searching functionality for command history prompts. Since
it is very possible that we use prompt written before, it could potentially
save lots of time typing.
+** AI Model Selection
+Available models (as of 2025-01-26):
+- anthropic/claude-3-5-sonnet-20241022 (recommended)
+- o3-mini (cost-effective)
+- gemini/gemini-exp-1206 (free)
+- r1 (compact context)
+- deepseek/deepseek-chat (budget-friendly)
-You can have helm-based completion with run the following code, after install
helm library:
+* Optional Features
+** Helm Integration
+For fuzzy command history searching:
#+BEGIN_SRC emacs-lisp
- (use-package aider
- :straight (:host github :repo "tninja/aider.el" :files ("aider.el"
"aider-helm.el")))
+(use-package aider
+ :straight (:host github :repo "MatthewZMD/aidermacs" :files ("aider.el"
"aider-helm.el")))
#+END_SRC
-*** Aider prompt file
-
-- Use C-c a p to open the repo specific prompt file. You can use this file to
organize tasks, and write prompt and send them to the Aider session. multi-line
prompts are supported.
-
-- The following example shows C-c C-c key pressed when cursor is on the prompt.
-
-[[file:./aider_prompt_file.png]]
-
-* Most used features (integrated into the aider menu)
-
-*** Aider session management:
- - (`aider-run-aider`): Creates a comint-based, *git repo-specific Aider
session* for interactive conversation.
- - Git repository identification is based on the current file's path
- - Multiple Aider sessions can run simultaneously for different Git
repositories
-When being called with the universal argument (`C-u`), a prompt will offer the
user to change the content of `aider-args` for this session.
- - (`aider-switch-to-buffer`): Switch to the Aider buffer.
- - use "^" in the menu to toggle open aider session in other window inside
current frame, or open a dedicate frame for aider session
-
-*** More ways to add files to the Aider buffer:
- - use "@" in the menu to toggle add file between read-write mode and
read-only mode
- - (`aider-add-current-file`): Add the current buffer file.
- - (`aider-add-files-in-current-window`): Add all buffers in the current
window.
-
-*** Write code:
- - (`aider-function-or-region-refactor`): If a region is selected, ask Aider
to refactor the selected region. Otherwise, ask Aider to change / refactor the
function under the cursor.
- - (`aider-implement-todo`): Implement requirement in comments in-place, in
current context.
- - If cursor is on a comment line, implement that specific comment in-place.
- - If there is a selection region of multi-line comments, implement code
for those comments in-place.
- - If cursor is inside a function, implement TODOs for that function.
- - Otherwise implement TODOs for the entire current file.
-
-*** Support for Unit Test / Test Driven Development:
- - (`aider-write-unit-test`): Generate comprehensive unit tests for the
current function or file. If the cursor is on a test function, implement the
test function.
- - (`aider-fix-failing-test-under-cursor`): Place cursor on a failing test
function and ask Aider to analyze and fix the code to make tests pass. You can
provide more information of failed test case to help aider figuring out how to
fix the source code.
-
-*** Explain code:
- - (`aider-ask-question`): Ask Aider a question about the code in the current
context. If a region is selected, use the region as context.
- - (`aider-function-or-region-explain`): If a region is selected, ask Aider
to explain the selected region. Otherwise, ask Aider to explain the function
under the cursor.
- - (`aider-explain-symbol-under-point`): Ask Aider to explain the symbol
under cursor, given the line as context.
-
-*** Model Selection:
- - (`aider-change-model`): Interactively select and change AI model in
current aider session
- - Customize `aider-popular-models` to define your preferred models list.
Default models are (as date of 2025-01-26):
- - anthropic/claude-3-5-sonnet-20241022 (really good in practical)
- - o3-mini (new released. very powerful, not expensive)
- - gemini/gemini-exp-1206 (free)
- - r1 (performance matches o1, price << claude sonnet. weakness: small
context)
- - deepseek/deepseek-chat (chatgpt-4o level performance, price is 1/100.
weakness: small context)
-
-*** And More:
-You can add your own Elisp functions to support your specific use cases. Feel
free to ask Aider/`aider.el` to help you create them.
-
-* My personal development experience using aider.el
-
-- Here I just share my personal experience. You might have different / better
way to use aider.el.
-
-** Feature development
-
-1. Start an Aider session associated with the current Git repository by
running the command “aider-run-aider”. This links the session to the project
context.
-
-2. Next, consider including relevant files in the session using commands like
“aider-add-current-file” or “aider-add-files-in-current-window”. This supplies
Aider with additional, useful context.
-
-3. When making changes, you might be either adding new code or modifying
existing code.
- - *Adding new code* via one-line comment implementation:
- For instance, suppose you encounter the following Python snippet:
-
- #+BEGIN_SRC python :eval never
- # TODO: Implement a function that checks if a number is prime
- #+END_SRC
-
- With the cursor positioned on the TODO comment line, running
“aider-implement-todo” will send only that inline comment to Aider, which may
then generate revised code—for example, a complete implementation of an
is_prime function—while preserving the existing code. For instance, Aider might
produce:
-
- #+BEGIN_SRC python :eval never
- def is_prime(n):
- if n <= 1:
- return False
- for i in range(2, int(n ** 0.5) + 1):
- if n % i == 0:
- return False
- return True
- #+END_SRC
-
- This example demonstrates how aider-implement-todo can assist in
introducing new code. (This command may also be useful for some documentation
tasks.)
-
- - If the suggested change is not completely satisfactory, you can decline
it (for example, by entering "N"). After declining, use the “Ask Question”
command (or type /ask in the aider session buffer) to request further
modifications with detailed guidance. Once you receive an acceptable
suggestion, confirm it using the “Go Ahead” command (or type "go ahead" in the
aider session buffer).
-
- - *Change existing code* for an existing function, class, or code block:
- 1. If you only need to modify a portion of the code, select the relevant
region; otherwise, simply place the cursor inside the target function or class.
- 2. Execute the “aider-function-or-region-refactor” command.
- 3. When prompted, provide a clear description of the intended change
(e.g., “Rename variable 'temp' to 'result'” or “Make the function static”).
- 4. A revised version of the code, incorporating your suggestions, will be
generated while preserving the overall structure.
- 5. Review the output; if further refinement is required, request
additional adjustments using “Ask Question” and confirm them with “Go Ahead”
until the desired result is achieved.
-
- - Note: Alternative commands like `aider-architect-discussion` and
`aider-code-change` are also available, though they may offer less context
sensitivity than the commands described above.
-
-4. *Generate tests*
- It is recommended to validate and iteratively improve the feature using
unit test commands such as “aider-write-unit-test” and
“aider-fix-failing-test-under-cursor.” Although AI-generated code can provide a
valuable starting point, it may sometimes introduce subtle issues. Running
tests both before and after integrating changes ensures that each modification
is verified. Running the full test suite after every change is advised to catch
any issues early.
-
- (As an aside, a projectile function is currently employed to switch
between the main code and test code and add them to the session—but further
improvements to include test code seamlessly are always welcome.)
-
-5. *Refactor code and tests*
- Finally, you can further refactor the AI-generated code and tests as
needed—either using additional prompts or manual adjustments—to best meet the
project’s requirements.
-
-* Screenshot
-
-[[file:./screenshot.png]]
-
-- The screenshot above shows Aider being asked to generate an aider-help
function and add its corresponding entry to the menu (top right window).
-- Aider successfully received the command and generated the appropriate commit
(bottom left).
-
-* [[./examples][Example Application Written with aider.el]]
-
-* FAQ
-
-- How to enter multi-line prompts in aider session buffer?
- - aider itself support that,
[[https://aider.chat/docs/usage/commands.html#entering-multi-line-chat-messages][doc]].
I used the tag way and it works well for me.
- - use aider prompt file (C-c a p) to write multi-line prompts (we don't want
them to go away right? especially if it is not perfect and need to be modified,
and we might want to reuse it sometime later).
+** Prompt Management
+Access repository-specific prompt files with =C-c a p= for organizing and
reusing prompts.
-* Other Emacs AI coding tool
+* Development Workflow
-- Inspired by, and Thanks to:
- - [[https://github.com/shouya/ancilla.el][ancilla.el]]: AI Coding Assistant
support code generation / code rewrite / discussion
- - [[https://github.com/xenodium/chatgpt-shell][chatgpt-shell]]: ChatGPT and
DALL-E Emacs shells + Org Babel, comint session based idea
- - [[https://github.com/copilot-emacs/copilot.el][copilot.el]]: Emacs plugin
for GitHub Copilot
- - [[https://github.com/chep/copilot-chat.el][copilot-chat.el]]: Chat with
GitHub Copilot in Emacs
- - [[https://github.com/karthink/gptel][gptel]]: Most stared / widely used
LLM client in Emacs
+1. Start an Aider session (=aider-run-aider=)
+2. Add relevant files to the session
+3. Implement or modify code using:
+ - =aider-implement-todo= for new code
+ - =aider-function-or-region-refactor= for existing code
+4. Generate and run tests
+5. Refine the implementation through additional prompts or manual edits
