branch: elpa/aidermacs
commit 2d39bfa5b3d89288e1424e43006af1bf9df69d4b
Author: Mingde (Matthew) Zeng <matthew...@posteo.net>
Commit: Mingde (Matthew) Zeng <matthew...@posteo.net>
Improve README
---
CONTRIBUTING.md | 2 +-
README.md | 196 ++++++++++++++++++++++++++------------------------------
aidermacs.el | 24 ++++---
3 files changed, 107 insertions(+), 115 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 51ef6537dc..fc65046b83 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,4 +5,4 @@ Aidermacs thrives on community involvement. We believe that the
best software is
- 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!
+Your contributions are essential to making Aidermacs the best AI pair
programming tool in Emacs!
diff --git a/README.md b/README.md
index 27f871eadf..f51dbfaa05 100644
--- a/README.md
+++ b/README.md
@@ -4,16 +4,19 @@
# Aidermacs: AI Pair Programming in Emacs
-## Introduction
+Miss using [Cursor](https://cursor.sh) but prefer living in Emacs? Aidermacs
brings Cursor-like AI-powered development to your Emacs workflow by integrating
[Aider](https://github.com/paul-gauthier/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:
-Miss using [Cursor](https://cursor.sh) but prefer working in Emacs? Aidermacs
brings Cursor-like AI-powered development to your Emacs workflow by integrating
[Aider](https://github.com/paul-gauthier/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:
+Key features:
- 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
+- Broad language support including Python, JavaScript, TypeScript, PHP, HTML,
CSS, etc.
+- Compatibility with leading AI models like Claude 3.5 Sonnet, DeepSeek, and
GPT-4o, etc.
+
+## Why Aidermacs?
+
+Aidermacs delivers an Emacs-centric experience by deeply integrating with
Emacs paradigms, made by Emacs users, for Emacs users. This includes
intelligent model selection, flexible terminal backend support (comint and
vterm), smarter syntax highlighting, enhanced file management, streamlined
transient menus, and more.
### Community-Driven Development
@@ -24,56 +27,7 @@ Aidermacs thrives on community involvement. We believe that
the best software is
- 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 is designed to provide a more Emacs-native experience while still
integrating with [Aider](https://github.com/paul-gauthier/aider). It began as a
fork of [aider.el](https://github.com/tninja/aider.el), but has since diverged
significantly to prioritize Emacs workflow integration.
-
-While `aider.el` strictly mirrors Aider's CLI behavior, `Aidermacs` is built
around Emacs-specific features and paradigms. This design philosophy allows you
to harness Aider's powerful capabilities through a natural, Emacs-native coding
experience.
-
-With `Aidermacs`, you get:
-
-1. Intelligent Model Selection
- - Automatic discovery of available models from multiple providers
- - Real-time model compatibility checking
- - Seamless integration with your configured API keys
- - Caching for quick access to frequently used models
- - Support for both popular pre-configured models and dynamically discovered
ones
-
-2. 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
-
-3. Smarter Syntax Highlighting
- - AI-generated code appears with proper syntax highlighting in major
languages.
- - Ensures clarity and readability without additional configuration.
-
-4. 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.
-
-5. Enhanced File Management from Emacs
- - List files currently in chat with `M-x aidermacs-list-added-files`
- - Drop specific files from chat with `M-x aidermacs-drop-file`
- - View output history with `M-x aidermacs-show-output-history`
- - Interactively select files to add with `M-x
aidermacs-add-files-interactively`
- - and more
-
-6. Greater Configurability
- - `Aidermacs` offers more customization options to tailor the experience to
your preferences.
-
-7. Streamlined Transient Menu Selection
- - The transient menus have been completely redesigned to encompass
functionality and ergonomics, prioritizing user experience.
-
-8. Community-Driven 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 🚀
+Your contributions are essential to making Aidermacs the best AI pair
programming tool in Emacs!
## Installation
@@ -160,8 +114,6 @@ This key allows you to enter multiple lines without sending
the command to Aider
## Usage
-This section provides a step-by-step guide on how to use Aidermacs for
AI-assisted pair programming in Emacs.
-
### Getting Started
The main interface to Aidermacs is through its transient menu system (similar
to Magit). Access it with:
@@ -176,59 +128,42 @@ Or bind it to a key in your config:
(global-set-key (kbd "C-c a") 'aidermacs-transient-menu)
```
-### Core Workflow
-
-#### 1. Start a Session
-From the transient menu:
-- `a` Start/open session (auto-detects project root)
-- `.` Start in current directory (good for monorepos)
-- `^` Toggle "Start in New Frame" option
-- `o` Change AI model
-- `s` Reset session
-- `x` Exit session
-
-The session buffer will be named `*aidermacs:your-repo-name*` where you can
interact with the AI.
-
-#### 2. Quick Actions
-Most common operations are available directly:
-- `f` Add current file to chat
-- `c` Request code changes
-- `r` Refactor code at point/region
-- `d` Drop current file from chat
-- `g` Accept AI's proposal ("go ahead")
-- `u` Undo last change
-- `Q` Ask general question
-- `q` Ask question about current code
-- `e` Explain code at point/region
-- `p` Explain symbol under point
-
-#### 3. Specialized Commands
-Access more specific commands through submenus:
+The main interface to Aidermacs is through its transient menu system. Here's a
breakdown of the available commands:
+
+##### Core Actions
+- `a`: Start/Open Session (auto-detects project root)
+- `.` : Start in Current Directory (good for monorepos)
+- `o`: Change Model
+- `s`: Reset Session
+- `x`: Exit Session
+
+##### Quick Actions
+- `f`: Add Current File
+- `c`: Code Change
+- `r`: Refactor
+- `g`: Go Ahead
##### File Commands (`F`)
-- Add files: current (`f`), read-only (`r`), window (`w`), directory (`d`),
marked in dired (`m`)
-- Drop files: specific (`j`), current (`k`)
-- List files in chat (`l`)
+- Add Files: current (`f`), interactively (`i`), read-only (`r`), window
(`w`), directory (`d`), dired marked (`m`)
+- Drop Files: interactively (`j`), current (`k`), all (`a`)
+- Other Actions: list files (`l`)
##### Code Commands (`C`)
-- Code changes (`c`)
-- Refactoring (`r`)
-- Implement TODOs (`i`)
-- Testing: write (`t`), fix (`T`)
-- Debug exceptions (`x`)
-- Undo changes (`u`)
-
-##### Understanding Code
-- `m` Show last commit
-- `q` Ask questions
-- `e` Explain code at point/region
-- `p` Explain symbol under point
-
-##### Other Features
-- `H` View session history
-- `L` Copy last AI output
-- `l` Clear buffer
-- `h` Get help
+- Code Actions: code change (`c`), refactor code (`r`), implement TODO (`i`),
write tests (`t`), fix test (`T`), debug exception (`x`), undo changes (`u`)
+
+##### Understanding
+- `m`: Show Last Commit
+- `Q`: Ask General Question
+- `q`: Ask Question
+- `e`: Explain This Code
+- `p`: Explain This Symbol
+
+##### Others
+- `H`: Session History
+- `L`: Copy Last Aidermacs Output
+- `O`: Clear Model Selection Cache
+- `l`: Clear Buffer
+- `h`: Aider Help
### Working with Code Blocks
@@ -267,3 +202,52 @@ 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
+
+## Aidermacs vs aider.el
+
+Aidermacs is designed to provide a more Emacs-native experience while still
integrating with [Aider](https://github.com/paul-gauthier/aider). It began as a
fork of [aider.el](https://github.com/tninja/aider.el), but has since diverged
significantly to prioritize Emacs workflow integration.
+
+While `aider.el` strictly mirrors Aider's CLI behavior, `Aidermacs` is built
around Emacs-specific features and paradigms. This design philosophy allows you
to harness Aider's powerful capabilities through a natural, Emacs-native coding
experience.
+
+With `Aidermacs`, you get:
+
+1. Intelligent Model Selection
+ - Automatic discovery of available models from multiple providers
+ - Real-time model compatibility checking
+ - Seamless integration with your configured API keys
+ - Caching for quick access to frequently used models
+ - Support for both popular pre-configured models and dynamically discovered
ones
+
+2. 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
+
+3. Smarter Syntax Highlighting
+ - AI-generated code appears with proper syntax highlighting in major
languages.
+ - Ensures clarity and readability without additional configuration.
+
+4. 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.
+
+5. Enhanced File Management from Emacs
+ - List files currently in chat with `M-x aidermacs-list-added-files`
+ - Drop specific files from chat with `M-x aidermacs-drop-file`
+ - View output history with `M-x aidermacs-show-output-history`
+ - Interactively select files to add with `M-x
aidermacs-add-files-interactively`
+ - and more
+
+6. Greater Configurability
+ - `Aidermacs` offers more customization options to tailor the experience to
your preferences.
+
+7. Streamlined Transient Menu Selection
+ - The transient menus have been completely redesigned to encompass
functionality and ergonomics, prioritizing user experience.
+
+8. Community-Driven 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 🚀
diff --git a/aidermacs.el b/aidermacs.el
index b7a81914d6..67f3fc77bb 100644
--- a/aidermacs.el
+++ b/aidermacs.el
@@ -114,7 +114,7 @@ This function can be customized or redefined by the user."
(transient-define-prefix aidermacs-transient-file-commands ()
"File management commands."
["File Actions"
- ["Add File Actions"
+ ["Add Actions"
("f" "Add Current File" aidermacs-add-current-file)
("i" "Add File Interactively" aidermacs-add-files-interactively)
("r" "Add Current Read-Only" aidermacs-add-current-file-read-only)
@@ -124,9 +124,11 @@ This function can be customized or redefined by the user."
["Drop Actions"
("j" "Drop File Interactively" aidermacs-drop-file)
- ("k" "Drop Current File" aidermacs-drop-current-file)]
+ ("k" "Drop Current File" aidermacs-drop-current-file)
+ ("a" "Drop All Files" aidermacs-drop-all-files)]
- [("l" "List Files" aidermacs-list-added-files)]])
+ ["Other Actions"
+ ("l" "List Files" aidermacs-list-added-files)]])
(transient-define-prefix aidermacs-transient-code-commands ()
"Code modification commands."
@@ -137,7 +139,7 @@ This function can be customized or redefined by the user."
("t" "Write Tests" aidermacs-write-unit-test)
("T" "Fix Test" aidermacs-fix-failing-test-under-cursor)
("x" "Debug Exception" aidermacs-debug-exception)
- ("u" "Undo Change" aidermacs-undo-last-change)])
+ ("u" "Undo Auto Git Commit" aidermacs-undo-last-commit)])
;; Main transient menu
(transient-define-prefix aidermacs-transient-menu ()
@@ -154,10 +156,9 @@ This function can be customized or redefined by the user."
("f" "Add Current File" aidermacs-add-current-file)
("c" "Code Change" aidermacs-code-change)
("r" "Refactor" aidermacs-function-or-region-refactor)
- ("g" "Go Ahead" aidermacs-go-ahead)
- ("u" "Undo Change" aidermacs-undo-last-change)]
+ ("g" "Go Ahead" aidermacs-go-ahead)]
- ["Code & Files"
+ ["File & Code"
("F" "File Commands" aidermacs-transient-file-commands)
("C" "Code Commands" aidermacs-transient-code-commands)]
@@ -449,6 +450,13 @@ Sends the \"/ls\" command and returns the list of files
via callback."
(message "No files available to drop"))))
+;;;###autoload
+(defun aidermacs-drop-all-files ()
+ "Drop all files from the current chat session."
+ (interactive)
+ (aidermacs--send-command "/drop"))
+
+
;;;###autoload
(defun aidermacs-show-output-history ()
"Display the AI output history in a new buffer."
@@ -538,7 +546,7 @@ If Magit is not installed, report that it is required."
(message "Magit is required to show the last commit.")))
;;;###autoload
-(defun aidermacs-undo-last-change ()
+(defun aidermacs-undo-last-commit ()
"Undo the last change made by aidermacs."
(interactive)
(aidermacs--send-command "/undo"))
