Provide a sidebar like other editors

[cmacrae]

Hey @xenodium 👋 Thanks so much for all your hard work on making LLMs usable in this home we hold so dear :)

I played around with agent-shell today (fantastic work!) and one of the first things I found myself itching for was being able to toggle the agent buffer in a side panel. Typically when I'm working on a project, assisted by an agent, I like to compartmentalise it and call upon it when I need it. When I don't need it, it's nice to have it out of the way. Equally, I like being able to summon it back quickly/easily when I need it. I think other projects have gotten this right by packing this into a sidebar, typically to the right of the editor.

I took a stab at it and actually have built something which I'm already finding to be a really nice UX. Even more fun is that I used agent-shell to help me get it done 🕶️

I'll raise a PR so you can see what you think about the implementation.

[xenodium]

Thank you for filing the feature request and proposing a PR.

Before we focus on the PR, it'd be great to hash the feature out a little and then we can follow up with more PR/implementation details.

Your video does a great job showing what the feature can look like:

agent-shell.sidebar.demo.mov

Looking through the PR a little, I noticed we got provider-specific logic which will get tricky to maintain over time, specially when adding new providers. It's already been a pending task for me, but I intend to make all the agent-shell--start- commands to attempt reusing existing shells unless a prefix is provided (this creates a new instance). This may help the side bar cause to reuse/get the shell instance.

Getting back to hashing the feature out... As I'm understanding (please correct if otherwise), the feature offers:

1. Shells (new or existing) always launched/displayed in the side bar.
2. Swap shells.

• Is there any filtering involved?
• Does it only allow to swap to other shells within the same project?

3. Switching projects.

• How do we deal with indirectly switching projects? That is, I'm looking at a file in a project and then switch buffers to a file in a different project.
• How does the side bar deal with this?

We should consider how far we can get by using display-buffer-alist to achieve the side bar, which is a fairly standard way of dealing with Emacs window/arrangement. For example, in ready-player, I offer a configurable action with a default behaviour, but users can override to taste.

One thing, if I'm able to provide all the needed/generic APIs, we should also consider agent-shell-sidebar becoming a separate package. This would enable some modularity and also for users to pick and choose their preferred way to interact with the agent shells.

[xenodium]

I had a quick look at how we can make things a little more generic. Putting shell creation aside initially, I think this gets us fairly far with little code?

(defun agent-shell-project-buffers ()
  "Return all shell buffers in the same project as current buffer."
  (let ((project-root (agent-shell-cwd)))
    (seq-filter (lambda (buffer)
                  (with-current-buffer buffer
                    (and (derived-mode-p 'agent-shell-mode)
                         (string-prefix-p project-root
                                          (expand-file-name default-directory)))))
                (buffer-list))))

(defun agent-shell-toggle ()
  "Toggle agent shell display."
  (interactive)
  (let ((shell-buffer (seq-first (agent-shell-project-buffers))))
    (unless shell-buffer
      (user-error "No agent shell buffers available for current project"))
    (if (get-buffer-window shell-buffer)
        (delete-window (get-buffer-window shell-buffer))
      (select-window (display-buffer shell-buffer
                                     '((display-buffer-in-side-window)
                                       (side . right)
                                       (slot . 0)
                                       (window-width . 70)
                                       (dedicated . t)
                                       (window-parameters . ((no-delete-other-windows . t)))))))))

[xenodium]

Now with switching helpers

(defun agent-shell-toggle ()
  "Toggle agent shell display."
  (interactive)
  (let ((shell-buffer (seq-first (agent-shell-project-buffers))))
    (unless shell-buffer
      (user-error "No agent shell buffers available for current project"))
    (if (get-buffer-window shell-buffer)
        (delete-window (get-buffer-window shell-buffer))
      (agent-shell--display-buffer shell-buffer))))

(defun agent-shell-switch-project-buffers ()
  "Switch to any available agent shell buffer in project."
  (interactive)
  (agent-shell--display-buffer
   (completing-read "Switch agent shells (by project): "
                    (or (agent-shell-project-buffers)
                        (user-error "No agent shells in this project")))))

(defun agent-shell-switch-buffers ()
  "Switch to any other available agent shell buffer."
  (interactive)
  (agent-shell--display-buffer
   (completing-read "Switch agent shells (all available): "
                    (or (agent-shell-buffers)
                        (user-error "No agent shells in this project")))))

(defun agent-shell-project-buffers ()
  "Return all shell buffers in the same project as current buffer."
  (let ((project-root (agent-shell-cwd)))
    (seq-filter (lambda (buffer)
                  (with-current-buffer buffer
                    (string-prefix-p project-root
                                     (expand-file-name default-directory))))
                (agent-shell-buffers))))

(defun agent-shell-buffers ()
  "Return all shell buffers."
  (seq-map #'buffer-name
           (seq-filter (lambda (buffer)
                         (with-current-buffer buffer
                           (derived-mode-p 'agent-shell-mode)))
                       (buffer-list))))

(defun agent-shell--display-buffer (shell-buffer)
  "Toggle agent shell display."
  (interactive)
  (select-window (display-buffer shell-buffer
                                 '((display-buffer-in-side-window)
                                   (side . right)
                                   (slot . 0)
                                   (window-width . 70)
                                   (dedicated . t)
                                   (window-parameters . ((no-delete-other-windows . t)))))))

[cmacrae]

Thanks for taking the time to review this so thoroughly and sharing your ideas around the code!

You're absolutely right about the provider-specific logic being a maintenance burden, any changes to provider interfaces would need updating in two places, which isn't great.

I like your use of display-buffer-alist as the primary mechanism and keeping the sidebar as a thin display layer and the agent-shell-project-buffers & agent-shell-buffers functions are elegant. The shell reuse API sounds like it would solve a lot of the architectural issues.

That said, I think there are some UX niceties in my implementation that are worth preserving (even if they add complexity):

1. Per-project state: Each project remembers its own sidebar buffer, provider choice, last-focused window, and width settings, maintaining independent sidebar state per project. I modelled this after how I personally prefer to use treemacs (which inspired most of the implementation). When you switch to a buffer in a different project, the previous sidebar stays attached to its original project - each sidebar is independent and bound to one project. So if you have a sidebar for project A open and switch to a buffer in project B, toggling the sidebar will find (or create) project B's sidebar. Does that make sense?

2. Automatic width management: Support for percentage-based sizing, min/max constraints, responsive recalculation when locked, and preservation of manual resizing when unlocked. This makes the sidebar adapt nicely to different screen sizes and scenarios.

3. Focus toggling: agent-shell-sidebar-toggle-focus enables quick keyboard-driven back-and-forth between the sidebar and your working buffer, which I've found to feel natural and convenient.

4. Lock/unlock behavior: agent-shell-sidebar-locked controls whether the sidebar can be resized manually and whether other-window (C-x o) can navigate to it. When locked, it stays out of the way; when unlocked, it behaves like a normal window.

5. Provider persistence: The sidebar remembers which provider you used for each project, so toggling it back doesn't require re-selecting.

I'm very happy to maintain this as a separate package (as you suggested), which would give users choice in how they interact with agent-shell. To make that work well, I'd love to understand a bit more about the APIs you're planning:

• Any idea on how the shell reuse API would work? Would it be a parameter to the existing agent-shell--start-* functions, or a separate set?
• Do you have a preference on supporting multiple agent shells per project, or just one? My implementation assumes one-sidebar-per-project, which is an intentional design choice, based on my preferences.

If you do implement the generic APIs, I'm happy to refactor my implementation to use them and eliminate the provider-specific duplication :)

Thanks again for your the review and code you shared!

[xenodium]

Thanks for all the details

I like your use of display-buffer-alist as the primary mechanism and keeping the sidebar as a thin display layer and the agent-shell-project-buffers & agent-shell-buffers functions are elegant.

I've now added a basic form of this, but doesn't behave like a side bar. See agent-shell-display-action which basically replaces current buffer window with new/reused shell.

I'm very happy to maintain this as a separate package

👍

I'd love to understand a bit more about the APIs you're planning

I think I've now pushed everything you may need (let me know if otherwise) in 0.4.1 or newer:

• agent-shell-select-config to select an agent configuration (also see agent-shell-agent-configs).
• agent-shell-start to start a selected config.
• You can see usage and basic reuse in agent-shell.
• Maybe of interest agent-shell-project-buffers and agent-shell-buffers.

edit: typo

[cmacrae]

Great! The new API made this really easy to implement: agent-shell-sidebar

Thanks very much for going over this with me, it was really helpful :)

[xenodium]

Great! The new API made this really easy to implement: agent-shell-sidebar

Nice work!

I noticed we both have a similar function agent-shell-cwd and agent-shell-sidebar--get-project-root if you're keen to consolidate. Also minor stylistic comment, let* with a single variables can just be let.

Thanks very much for going over this with me, it was really helpful :)

Thanks for being open to alternatives and iterating on it.

Liked to agent-shell-sidebar from the agent-shell README.

Also thank you for sponsoring ❤️

[xenodium]

I've mentioned agent-shell-sidebar in my blog post: https://xenodium.com/agent-shell-0-5-improvements#agent-shell-sidebar-(new-package)

FYI: Comment from Hacker News https://news.ycombinator.com/item?id=45561719

I wish that agent-shell-sidebar had some screenshots though so I could see what it actually does.

[cmacrae]

Ah, thanks so much for the mention in your blog post and for sharing! Thanks for forwarding that feedback, I'll add a gif to the README 👍