Another month, another agent-shell update. If you missed the last one, have a look at the 0.63 update. While this post showcases the latest highlights, the full list of changes is far chunkier than what we'll cover.
agent-shell
?agent-shell is a native Emacs mode to interact with AI agents powered by ACP (Agent Client Protocol).
Since inception in September last year (yikes nearly a year), agent-shell
has featured a shell-like experience, powered by comint mode. There's also viewport mode (via agent-shell-prefer-viewport-interaction
), if you prefer a more focused experience, and now we have chat mode
.
Chat mode fuses comint
mode with a more traditional chat-like labelling experience.
We're living on the edge here, so chat mode is now enabled by default. Ok not really that edgy, it's fairly safe (powered overlays) and can be disabled entirely via (setq agent-shell-chat-mode-enabled nil)
. Chat mode itself is a minor mode, so you can always toggle it on and off via M-x agent-shell-chat-mode
.
In the last post, we talked about making agent-shell
less chatty with more grouping for the likes of tool calls and agent thinking, all collapsed by default. If that's far too quiet, you can expand by default via (setq agent-shell-activity-group-expand-by-default t)
. If you found these two settings either too quiet or too chatty, we now have a third alternative via (setq agent-shell-activity-group-expand-by-default 'latest)
. When set, only the latest grouped activity is expanded by default, and automatically collapsed when the agent moves on to something else.
I've become quite fond of this feature (thank you @nhojb for the PR), so yes. It's also enabled by default.
Queuing received some improvements. The related commands have been consolidated under agent-shell-prompt-queue.el
. You can queue prompts while the agent is busy, then view, resume, or drop pending prompts via M-x agent-shell-prompt-queue
, M-x agent-shell-prompt-queue-resume
, and M-x agent-shell-prompt-queue-remove
. The pending queue is now shown after each new submission.
M-x agent-shell-prompt-compose
opens a dedicated buffer for crafting a prompt, and it's now more independent of the shell. You can invoke it from any buffer (it resolves to the right shell), C-c C-c
sends and returns you to whatever you were doing (fire and forget), and C-u C-c C-c
submits the prompt and immediately lets you craft another queued prompt.
Shell initialization may take a second or two, depending on what agent you're using, which meant you had to wait for initialization before you could start typing into your new shell. Unnecessary, so that's no longer the case. Shell prompts are now offered as soon as possible, so one can get typing.
While Markdown lists are easily digestible without special rendering, we can do better than that, so we now give them a better treatment with normalized padding, indentation, and of course, civilized bullets.
TAB navigation made it into agent-shell
fairly early on. I love being able to TAB my way into any section in the buffer and press RET to toggle folding. That's great and all, but we can make the navigation experience richer by welcoming the likes of Markdown source blocks, links, and images to the navigation party. Why these in particular? They are all actionable by RET too, of course.
While you'd rightly assume RET opens links to local text files in Emacs and delegates to browsers when needed, Markdown source blocks and images get a similar treatment. While their respective RET actions may not be as obvious, we can certainly make them much more discoverable, so we now add hints. Landing point on an actionable item now echoes a hint of what you can do and which key does it (say, "Press RET to copy" on a source block, "Press + to enlarge" on an image, and so on). Hints are also shown on mouse over events.
While agent-shell
offers agent-shell-markdown-image-max-width
for customizing image sizes, it's fairly restrictive. Not all images are the same, so why force them all to fit within the same constraint? agent-shell-markdown-image-max-width
continues to offer a preferred default, but you can now scale images differently by getting the agent to annotate Markdown images with Pandoc-style link attributes.
The attribute block goes right after the image, taking a width
and/or height
in pixels or percentages:
{width=300}
{width=50% height=200}
I may be sweating the small stuff here, but this was really grinding my gears. We have lovely Markdown table rendering, which I'm glad we do as LLMs aren't always great at producing perfectly aligned tables. In the best of cases, the LLMs align the table perfectly, but it's just too wide for our Emacs window. Luckily, our lovely rendering also wraps cells to make them fit into our window. The thing is, all that lovely rendering goes out the door the moment you either resize your Emacs frame or merely split your window, resulting in a monstrosity like this:
I know. I'm sweating the small stuff here, but hey we don't have to live like this. Emacs has all the hooks in the world, so let's track window changes and rejoin the civilized world.
On a much smaller scale, I also wanted auto resize for images, so here you have it…
While we can influence image size at render time, this can still generate undesirable image dimensions, so we can now rescale all images in buffer on demand.
Sometimes a hammer really isn't the right tool, so we can now also rescale an image at point.
Opening a local file (from a link, image, or @file
mention) now routes through agent-shell-file-display-action
, a standard display-buffer
action you can customize. The default reuses a window already showing the file, or takes over the current one.
If you'd like a different window arrangement, you could do something like:
(setq agent-shell-file-display-action
'(display-buffer-pop-up-window))
Following a local file link now pushes your origin onto xref's marker stack, so xref-go-back
(M-,
) brings you right back to where you were in your agent-shell
, just like other Emacs jumps.
Foldable fragments now use agent-shell-ui-fragment-map
and bind agent-shell-ui-toggle-fragment
. If you're not a fan of the RET binding to toggle folding, you can now use your preferred binding.
If TAB
is your jam, you can do something like:
(with-eval-after-load 'agent-shell-ui
(define-key agent-shell-ui-fragment-map
(kbd "TAB") #'agent-shell-ui-toggle-fragment))
If you prefer styling agent thoughts differently, a new agent-shell-thought-body
face lets you do just that.
Streaming performance also received some love. Thanks to @suhail-singh for the profiling and improvements, and to @Scott-Guest and @claytharrison for the trace analysis and benchmarking in #757.
The "Available config options" section now displays possible values.
agent-shell-agent-configs
can now be set to a function, letting you compute the available agent configurations dynamically rather than hard-coding a static list. The function is called on every access, so it stays current across code reloads.
Maybe you'd like to list only available agents. Here's a rough snippet.
(setq agent-shell-agent-configs
(lambda ()
(seq-filter
(lambda (maker)
(when-let* ((client (ignore-errors
(funcall (map-elt (funcall maker) :client-maker)
(current-buffer))))
(command (map-elt client :command)))
(executable-find command)))
(agent-shell-default-agent-config-makers))))
agent-shell-subscribe-to
now broadcasts an agent-message-chunk
event, handy for external integrations that want to observe streamed output.
executable-find
now works correctly on remote hosts (#742 by @CeleritasCelery), smoothing out TRAMP-driven remote agents.
agent-shell-hq joins the family, offering an interface for managing multiple agent-shell
sessions.
If you peeked at the commit logs, you'll notice I've been working daily on agent-shell
, keeping up with project inflow. Since last month, 27 issues have been closed and 13 pull requests merged. As of today, the backlog sits at 11 open issues and 5 open PRs (versus 13 and 4 last time around). If there's something you'd like me to prioritize, feel free to ping.
Vendor-neutral tooling matters more than ever, and there are a couple of ways to help keep agent-shell
going. Some cost money, others just a click. All are appreciated ;)
agent-shell
is just me, an indie dev, while the tools it competes with have well-funded teams behind them. Time spent on agent-shell
is time away from work that pays the bills, so if it's useful to you, please consider sponsoring the project. And if your employer benefits from your agent-shell
use, nudge them to chip in too, they can typically contribute at a scale individuals can't.
GitHub stars help with exposure, attracting new users and potential sponsors. Starring agent-shell costs nothing and can potentially help bring in more funding, so if you don't mind a couple of clicks, the project can really use another GitHub star.
Thank you to all contributors for these improvements!
when-active
option to agent-shell-activity-group-expand-by-default
(agent-shell
Liking agent-shell
? Would like to see it evolve? Consider sponsoring the effort.