macher

A project-aware LLM editing toolset for Emacs, built on gptel.

https://github.com/user-attachments/assets/af8bed3d-913b-4365-9f71-85d969810d22

What is macher?

macher allows your LLM to read/search files in the current project, and propose edits in the form of patches, potentially involving multiple files. You can apply the patches directly to your project, or send them back for revision.

macher is a lightweight Emacs-native take on the editing workflows of more full-featured tools like Aider or Plandex. It works with any gptel backend that supports tool use.

It's great for "pseudo-agentic" workflows, for example when you want your LLM to implement a set of changes, maybe call other tools to do research, etc - but you want to review the aggregate changes before writing them to disk.

macher takes inspiration from gptel's flexibility and visibility. It doesn't touch your gptel globals (unless you tell it to) - it's just a set of presets, tools, and transforms that you can use as you like. Or you can use the built-in action commands for a quick and easy workflow.

Installation and configuration

macher is available on MELPA. Example configuration with use-package:

(use-package macher
  :custom
  ;; The org UI has structured conversations and nice content folding.
  (macher-action-buffer-ui 'org)

  :hook
  ;; Set up action buffer behavior to your liking.  Alternately, do
  ;; this more generally in your `gptel-mode-hook'.
  (macher-action-buffer-setup
   . (lambda ()
      ;; Auto-scroll responses.
      (setq-local window-point-insertion-type t)
      ;; Wrap lines.
      (visual-line-mode 1))

  :config
  ;; Recommended - register macher tools and presets with gptel.
  (macher-install)

  ;; Recommended - enable macher infrastructure for tools/prompts in
  ;; any buffer.  (Actions and presets will still work without this.)
  (macher-enable)

  ;; Adjust buffer positioning to taste.
  ;; (add-to-list
  ;;  'display-buffer-alist
  ;;  '("\\*macher:.*\\*"
  ;;    (display-buffer-in-side-window)
  ;;    (side . bottom)))
  ;; (add-to-list
  ;;  'display-buffer-alist
  ;;  '("\\*macher-patch:.*\\*"
  ;;    (display-buffer-in-side-window)
  ;;    (side . right)))
  )

(use-package gptel
  :config
  ;; Optional - set up macher as soon as gptel is loaded.
  (require 'macher))

macher-install and macher-enable are intended to be very unintrusive, and shouldn't have any effect on non-macher requests, but they do modify the global gptel environment. See the docstrings if you want more specifics. Action commands will work regardless of whether you've run these.

Usage

Presets/Tools

After calling (macher-install), you can use macher presets and tools in any gptel request or buffer.

https://github.com/user-attachments/assets/d6a5c8ee-559e-42ab-a240-381f7187cb06

Built-in presets:

• @macher: Full editing capabilities. Adds tools to read, search, and edit files. Changes are captured in memory and displayed as a patch. Also inherits @macher-system.

• @macher-ro: Read-only access. Adds tools to read and search files, but no editing tools. Also inherits @macher-system.

• @macher-tools: Tools only. Enables all macher tools without modifying the system prompt.

• @macher-system: Ensure system prompt includes workspace context (project name and files list). Useful when you want the LLM to understand your project structure but don't need file access. See macher-context-string-placeholder and macher-context-string-function.

• @macher-system-commit: Commits the current workspace context into the system prompt, replacing the dynamic placeholder with a static snapshot. Useful to avoid cache churn in long conversations.

• @macher-base: Utility preset that enables macher tool infrastructure. This gets applied automatically when using other macher presets, but you may want to apply it globally via macher-enable, if you want to use macher tools and/or dynamic context in more generic contexts. This adds transforms that run on every outgoing request, which:

  • provide macher tools with a shared editing environment
  • replace instances of the macher-context-string-placeholder in the system prompt

  This preset shouldn't have any effect on requests that don't use macher tools or include the placeholder.

All built-in presets can safely be repeatedly applied.

You can also manage macher tools directly from the gptel-menu.

Actions

Actions are convenience commands that use macher presets with a specific workflow:

• A description of your current location in the code is generated (see macher-focus-string).
• A prompt is captured based on the current selection or manual input.
• The prompt is sent in a dedicated actions buffer, with a preset applied.

The built-in actions are:

• macher-implement: Request an implementation based on selected text or manual input. Uses @macher.
• macher-revise: Request revisions to the current patch. The patch content and original prompt are included automatically. Uses @macher.
• macher-discuss: Ask questions about the workspace. Uses @macher-ro.

Typical workflow:

1. Select text describing what you want to implement
2. Run M-x macher-implement
3. Review the patch in the diff buffer
4. Apply changes with C-c C-a (apply hunk) or M-x diff-apply-buffer
5. Use M-x macher-revise if you need changes

Other action-related commands:

• macher-action: Run any action from the macher-actions-alist.
• macher-abort: Cancel running action requests for the current workspace.
• macher-focus-string: Get a description of your current code location. When called interactively, yanks the description to the kill ring.

The actions buffer UI can be customized with macher-action-buffer-ui (see Customization).

When using the org-mode UI (via macher-action-buffer-ui and/or gptel-default-mode), macher will set a GPTEL_TOPIC for outgoing actions, so you can continue conversations directly in the action buffer using gptel-send.

You can define custom actions in macher-actions-alist.

Workspace context

macher can add information about the current workspace (project name, location, file listings) to your system prompt.

If you've called (macher-enable) and/or activated @macher-base, any instances of the macher-context-string-placeholder (default: "[macher_placeholder]") in your system prompt will be replaced with a description of the request buffer's workspace.

The @macher, @macher-ro, and @macher-system presets will append the placeholder automatically to your system prompt (unless it's already there).

You can also use the macher-context-string-placeholder in your own directives to control placement or add info about the current project to any gptel request.

The workspace description can be customized by setting the macher-context-string-function.

Advanced usage

Workspaces

The workspace is the set of files macher can read and edit.

The workspace is determined by macher-workspace-functions. All file operations are restricted to the current workspace. By default, macher supports:

• project: A project.el project
• file: A single non-project file

A directory workspace type is also available for working in arbitrary directories (not managed by project.el). It is not enabled by default to avoid accidentally exposing broad directories to the LLM. To enable it, you can do something like:

(setq macher-workspace-functions '(macher-workspace-project macher-workspace-directory))

To add custom workspace types, customize macher-workspace-types-alist and macher-workspace-functions.

Request lifecycle

When you send a macher request with tools:

1. When a tool is first invoked, a macher-context struct is created - an ephemeral file-editing environment.
2. The LLM uses tools to read/search/edit files in this environment.
3. All changes are captured in memory (never written to disk).
4. When the request completes, macher-process-request-function generates a unified diff.
5. The patch is displayed in the workspace's patch buffer.

The macher-context is created lazily (only when tools are actually used) and maintains two versions of each accessed file:

• Original content: Read-only snapshot from first access
• Modified content: Editable copy where the LLM makes changes

Tools

Tools are defined in macher-tools and structured similarly to the MCP filesystem server.

Available tools:

• read_file_in_workspace: Read file contents
• search_in_workspace: Regex search (grep-like)
• list_directory_in_workspace: List directory contents
• edit_file_in_workspace: Make exact string replacements
• multi_edit_file_in_workspace: Multiple edits to one file
• write_file_in_workspace: Create or overwrite files
• move_file_in_workspace: Move/rename files
• delete_file_in_workspace: Delete files

When macher-install is called, these tools are registered with gptel but not activated. The @macher and @macher-ro presets activate the appropriate subsets.

You can also enable/disable them directly from the gptel menu, load them in restored gptel sessions, etc. Just make sure you call (macher-enable) or activate @macher-base - this adds a prompt transform that provides tools with a shared macher-context for outgoing requests.

To customize the available tools and presets, modify macher-tools or macher-presets-alist.

Customization

You can see customizable variables/sub-groups with M-x customize-group RET macher.

Actions

Workspace

Processing

Tools

FAQ

Why does diff-apply-buffer misbehave when the patch contains new or deleted files?

diff-mode in Emacs 30.x and below doesn't handle file creations/deletions well. The issue has been fixed upstream, and the fix will likely be included in the next major Emacs release. In the meantime, if this case comes up often for you, see #45 for possible workarounds.