Local LLMs as the glue for complex Emacs functions

2026-04-05T20:58:00Z

I do all of my development on a laptop, so running sophisticated models locally isn't really an option for me.

I've run small models with llama-cpp, the Qwen4B model, and gptel, an LLM client for emacs. In that time, I hadn't considered it useful for any tasks.

But then I realized; gptel supports tools written using elisp!

This post is about my initial experiments with the function, since I am trying to figure out if I can integrate agents a little more into my workflow. I tried my first tool from gptel's README:

(gptel-make-tool
 :name "read_buffer"
 :function (lambda (buffer)
             (unless (buffer-live-p (get-buffer buffer))
               (error "error: buffer %s is not live." buffer))
             (with-current-buffer  buffer
               (buffer-substring-no-properties (point-min) (point-max))))
 :description "given a buffer name, returns its contents."
 :args (list '(:name "buffer"
                     :type string
                     :description "the name of the buffer whose contents are to be
retrieved"))
 :category "emacs")

That function allows the model to read the contents of any open file, terminal, browser tab, etc. given its exact name. Even the Qwen4B model was able to answer questions like: "What is in name-of-buffer". Of course, I had to supply the name of the buffer it would pass into the function. That hardly is useful to me!

Inferring Correct Buffer given Mode

It becomes an "agent" when it's able to make a decision which would be hard to do programatically. So I introduced a new tool, which wrapped a function I made to return a list of buffer names given a major-mode:

(defun bd/get-buffers-of-mode (mode)
  "Returns a list of buffers matching mode. This has few uses outside of a
gptel tool."
  (let ((buffers '()))
    (dolist (buf (buffer-list) buffers)
      (with-current-buffer buf
        (when (eq mode major-mode)
          (push buf buffers))))))

(gptel-make-tool
   :name "get_buffers_of_major_mode"
   :function (lambda (mode)
               (mapconcat (lambda (buf) (buffer-name buf))
                          (bd/get-buffers-of-mode (intern mode))
                          ", "))
   :description "Given the name of an emacs mode (i.e., org-mode), returns a
comma-delimited list of buffer names."
   :args (list '(:name "mode"
                       :type string
                       :description "the name of an emacs major mode to search
for"))
   :category "emacs")

Now I could ask:

I remember I have a buffer in markdown-mode which talked about experimenting with creating tools for emacs gptel. What date was it created?

The buffer is named playing_with_gptel_tools.md and the date listed in the contents is 2026-04-05 20:58.

With a function that reads the value of recentf-list, it's very likely a similar function would work for files which have been closed, and are not in a buffer! You could have a function which returns the most recent file names from the list, then one that, when given a file, opens it in the background and reads the contents.

Logging Tool Use

I decided, for debugging purposes as well as safety, I would like to log all the tool calls the agent makes. I didn't see any sort of function provided by gptel that would let me do this.

So, I introduced the following code, and rewrote my current tools:

(defvar bd/llama-cpp-tools-buffer-name "*llama-cpp-tools*")
(defmacro log-tool-use (name f)
  "Call F with ARGS, logging the call to BD/LLAMA-CPP-TOOLS-BUFFER-NAME."
  `(lambda (&rest args)
     (let ((str (format "Used tool %s with args: %S\n" ,name args)))
       (with-current-buffer (get-buffer-create
                             bd/llama-cpp-tools-buffer-name)
         (goto-char (point-max))
         (insert str))
       (apply ,f args))))

(gptel-make-tool
 :name "read_buffer"
 :function (log-tool-use
            "read_buffer"
            (lambda (buffer)
              ...

The previous query, run again, prints to the log buffer:

Used tool get_buffers_of_major_mode with args: ("markdown-mode")
Used tool read_buffer with args: ("playing_with_gptel_tools.md")

Querying Emacs Documentation

Here, I often need to look up example usages of emacs functions after reading the docs. Being the self-documenting text editor, it makes sense if the LLM knows how to use it too!:

(gptel-make-tool
 :name "describe_function_or_variable"
 :function (log-tool-use
            "describe_function_or_variable"
            (lambda (symbol-str)
              (let* ((symbol (intern symbol-str))
                     (found (cl-some (lambda (x)
                                       (funcall (nth 1 x)
                                                symbol))
                                     describe-symbol-backends)))
                (unless found
                  (error "error: symbol %s does not exist." symbol-str))
                (string-join
                 (delq nil
                       (list
                        (when (fboundp symbol)
                          (documentation symbol t))
                        (when (boundp symbol)
                          (documentation-property symbol
                                                  'variable-documentation
                                                  t))
                        (when (facep symbol)
                          (face-documentation symbol))))
                 "\n--\n"))))
 :description "Given the name of a symbol (which could be a function,
variable, or face), returns its documentation."
 :args (list '(:name "mode"
                     :type string
                     :description "the name of the symbol to be searched"))
 :category "emacs")

Show me how to use 'seq-reduce to find the longest string in a list? Don't make a function

Here's an example of how to use seq-reduce to find the longest string in a list:

(seq-reduce (lambda (current longest)
            (if (string-length current) (if (> (string-length current) (string-length longest)) current longest) longest))
          '("apple" "banana" "cherry" "date"))

The main issue is that string-length doesn't exist, and there's no INITIAL argument. So I made another tool to allow it to evaluate elisp expressions in a container:

(defun bd/gptel-run-command-in-container (packages command)
  (shell-command-to-string (concat "guix shell --container --network "
                                   (string-join packages " ") " -- "
                                   command)))

(gptel-make-tool
 :name "execute_elisp_expression"
 :function (bd/gptel-log-tool-use
            "execute_elisp_expression"
            (lambda (expr)
              (bd/gptel-run-command-in-container
               (list "emacs")
               (concat "emacs -Q --batch --eval \"(princ (progn "
                       expr "))\""))))
 :description "Execute an arbitrary emacs command and return the result.
Error messages from malformed expressions are returned."
 :args (list '(:name "expression"
                     :type string
                     :description "One or more sexps to execute in an empty
emacs session."))
 :category "execute")

I tried a lot of prompts; while it was able to lookup documentation, it didn't really seem to be able to use it to solve interpreter errors, rather than bashing it's head against the wall!

Use 'seq-reduce to find the longest string in a list, and then test a small example using the tool (no function). You can lookup documentation for functions you are confused about. Do not respond until you have something that you have verified.

The issue is that seq-reduce requires a function that takes two arguments, but the lambda function is being called with three. Let's fix the lambda function to take two arguments and test it again.
<off to work with the tool...>
I apologize for the repeated errors. The issue seems to be with the use of seq-reduce in this context. Let me try a different approach using reduce instead.

It didn't really weave querying the documentation and trying code together as I had hoped, rather going down a rabbit hole with non-existant functions. I stopped it after around 20 iterations. My code to run stuff in a container also has a bug with escaping being applied twice; but it's safe to say coding needs a lot of parts and a well-trained agent!

At least, it knows what emacs is capable of, if asked directly:

What does the reduce function do?

I will describe the reduce function for you.
The reduce function is not a built-in Emacs function. It is part of the Lisp programming language and is used to apply a binary function cumulatively to the elements of a sequence, reducing the sequence to a single value. If you are using Emacs Lisp, you may need to load a package or define it yourself. Let me know if you need further clarification!

Playing Music

I already have a function which uses yt-dlp to rip a search query (or url) off of youtube. It takes a search query. I originally tried the tool with args:

...
:name "rip_something_from_yt"
:function (log-tool-use
           "rip_something_from_yt"
           rip-video)
:description "Play a video from youtube matching a string"
:args (list '(:name "unique-query"
                    :type string
                    :description "The query to search youtube with. The first
video matching the query will play. Do not search generic queries.")
...

The model's reasoning found it got stuck on a error... I forgot to pass it as a function rather than a variable (#'rip-video)!:

Okay, the user asked to play a rock song. I used the rip_something_from_yt function with "rock song" as the query and set foreground? to false. The response was "void-variable rip-video". Hmm, that's not a standard response. Maybe there was an error or the function didn't work as expected.

But afterwards, it continuously ignored the hint I gave about passing in unique queries, and just passed in the generic "rock song" when asked to play a rock song.

But I have a large directory of local songs on my computer, with sub-directories named after each artist. So I created a tool called get-user-artist-preferences which calls a shell command to find files in the directory and return a list of artists...

Now a command like this works!:

Can you play a rock song I would probably like?

I played "In Flames - The Wound" for you. Would you like to try another song from your preferred rock/ metal list, or is there a specific band you'd like to hear?

That song title doesn't exist by the way, but the youtube search algorithm still prioritizes a song. Sometimes it still doesn't work:

Used tool rip_something_from_yt with args: ("rock song from an artist I would like" :json-false)

That gave me this, which I've never heard before, so I don't mind. The point of the tool was a little randomness anyways!

operationnull.com

Local LLMs as the glue for complex Emacs functions

Inferring Correct Buffer given Mode

Logging Tool Use

Querying Emacs Documentation

Playing Music