New in v11.0.0 - ✨References can be pinned in the chat buffer

[olimorris]

Hope you're all enjoying the holiday season. I've totally needed the downtime and have been able to crank out v11.0.0 in the last day which had been on the cards for sometime. Alas, life and other priorities take over.

Introducing Pins

I'm pleased to announce that in the latest release you can now "pin" buffers and files in the chat buffer.

What does this mean exactly?

Well it means that every time you send a message to an LLM, the plugin will fetch the content from the pinned buffer/file and add it alongside your message. Previously, you would have had to manually re-add the contents of the reference to the message stack, which was a huge nuisance especially if you were using the @editor tool.

What.s.New.in.v11.0.0.mp4

How do I use it?

In the chat buffer, move over a reference and press gp to pin it. You will see a pin icon appear next to the reference. This icon can also be changed in your config. Of course, you can also unpin a reference. As seen in the video above, I actually choose to pin the reference in the second message but could have done it in the first.

What actually happens?

The whole contents of the buffer or file is added to the message stack before your current message. This happens every time for the duration that the reference is pinned. So please be mindful of token consumption.

Where does it work?

Pins work for the file and buffer slash commands and also for the #buffer variable.

Breaking Changes

There are two breaking changes in this release:

1. Agents have moved from strategies.agent to strategies.chat.agents. This should have happened looooong ago!
2. If you have custom variables that you use in the chat buffer, you'll need to ensure that the execute function within their class is renamed to output. You will also need to ensure that they implement a self.Chat.add_message function to add content to the chat buffer's message stack.

Roadmap for v11.*

Things I'm aiming for in v11.*:

• Performance improvements - I am going to scope Tree-sitter queries for better improvement across large chat buffers as well as investigate [Bug]: Potential memory leak on longer conversations #552 in more detail
• Allow the @editor agent to work with the File and Buffer slash commands. Currently it's scoped to work with line numbers and those functions just share the contents without line numbers
• Knowledge - I want to make it easier to open chat buffers with pre-defined references. This will make conversations more productive as you're not having to manually add knowledge (from the Fetch or Help slash commands)
• Automated Editing - I will strive to make it much easier to have the @editor and @cmd_runner tools working alongside pins to edit buffers or files, run tests, see the impact and determine next steps.

As always, if you like this release, I'm always open to a coffee 😃.

Wishing you all the best for 2025!!

[LintaoAmons]

I found the @editor tool is not very intuitive to use. There's only one shortcut to accept all the changes by hit ga right?

Or I have not got the right way to use it?

[bassamsdata]

Thank you for all those updates. Congratulations on reaching v11 as well!

As I understood from your plans for @editor, currently, only the #buffer variable is sending line numbers to the LLM, is that correct?

I’ve always wondered why we have the /buffer slash command and the #buffer variable (even though I know I can send multiple buffers in slash commands). Personally, I prefer sending the line numbers directly to the LLM.

[bassamsdata]

One more question, if I may: Is the logic for the pins entirely within the chat/init.lua file? because I have an idea in mind, but it hasn’t fully taken shape yet.

[olimorris]

I’ve always wondered why we have the /buffer slash command and the #buffer variable

Principally because the latter was implemented first. I don't want to disrupt someone's workflow by removing it and forcing them to adopt slash commands. Also, variables are just quicker to add to the chat buffer.

As I understood from your plans for @editor, currently, only the #buffer variable is sending line numbers to the LLM, is that correct?

Yep. Because I'm so time constrained, I'll generally wait until someone shouts about something before changing/implementing it. I had forgotten that the buffer slash command didn't include line numbers and therefore the @editor tool didn't work, so was surprised to see no one shout about it. Can only deduce that people mostly use #buffer when working with the tool.

[olimorris]

is the logic for the pins entirely within the chat/init.lua file? because I have an idea in mind, but it hasn’t fully taken shape yet.

...and the chat/keymaps.lua and chat/references.lua. Might also be worthwhile referring to the tests that accompanied the feature.

[bassamsdata]

Thank you for all this information.

Can only deduce that people mostly use #buffer when working with the too

alright, that's me as well :)

...and the chat/keymaps.lua and chat/references.lua. Might also be worthwhile referring to the tests that accompanied the feature.

Ah, I always forget that tests might be useful. Thank you

[GitMurf]

@olimorris so the new pinning functionality is working wonderfully! Nice work!

I do have one question / "issues" in reference to your quoted statement from above:

The whole contents of the buffer or file is added to the message stack before your current message. This happens every time for the duration that the reference is pinned. So please be mindful of token consumption.

You are indeed correct that the token count increases quite drastically depending on what file(s) you pin. One thing that would help tremendously though is if when you pin a buffer/file, you can have it remove the old messages that have the old copies of the buffer content. My main use case is to just want to be able to keep chatting with the most up to date buffer content (which the pin does) and rarely have use case of needing the countless other duplicate messages with the buffer content (at old states). The main problem is this exponentially increases the token count as each time you submit a message that is pinned, the token count just for the buffer contents turns into Token Count in Buffer * Message Count. A 500 line file has roughly 5,000 tokens in it, so after just 5 messages my token count for the buffers is 25,000 when in reality all I want is to keep submitting an updated copy of the same buffer content in a single message keeping a constant token count per buffer / file (5,000 tokens in this example).

It feels like maybe there is room for another "state" for pins where you have 1. Un-pinned 2. Pinned (as currently works) 3. Pinned (latest buffer contents only... removes the previous buffer content messages from the history).

Does this make sense? Thoughts?

[GitMurf]

@olimorris I am finding that the ability to do custom keymaps with access to the Chat instance in the callback is extremely powerful! ❤️

I am able to get access to chat messages and delete ones I want to pretty easily, but the remaining problem I am having is "syncing" the chat buffer content after deleting messages (i.e., remove the deleted messages from the chat buffer window and have it "refresh" the extmarks etc.). I have explored all the different methods I could think of after poking into the Chat / UI / References etc. methods, but I have not found the right method (or combo of methods) to do this.

Is there a simple / straightforward way to do this? Essentially reload the chat buffer based off the current Chat.messages state.

I even tried clearing the chat buffer window and trying to loop through the current messages and add them back in one at a time but have not found success with anything I have tried.

Perfect world would be a method to "refresh/reload chat window buffer based off current state of Chat.messages and Chat.references etc.". This would seemingly also be a step towards being able to save chat conversations and reload them later to continue conversation 🤔 🙂

Let me know if you have any thoughts or advice. For now I am totally fine with something potentially "hacky" until there are more "official" primitives available (or maybe there already are but I just couldn't find them!).

[olimorris]

One thing that would help tremendously .. you can have it remove the old messages that have the old copies of the buffer content.

It feels like maybe there is room for another "state" for pins where you have 1. Un-pinned 2. Pinned (as currently works) 3. Pinned (latest buffer contents only... removes the previous buffer content messages from the history).

My initial concerns with pins were solely around token management. I thought about enabling them for the symbol slash command but ultimately thought that would be somewhat useless for most users. I also thought about clearing out previously pinned buffers as well. Ultimately, I left that out of Pins v1.0 because I expected it wouldn't play well for those of us who run local LLMs. Also, I strongly prefer not to force change the history of a conversation for fear of sub-par responses and the dreaded h word. My expectation was after using the feature, users would unpin a buffer for future responses then re-pin it if required, if they're aiming to minimize tokens.

All this being said, I think a third state could be an option. Although, I'd want that ability to be scoped down to an adapter (possibly even model) level to allow local LLM users to turn it off. I'd need to think of a way to do that elegantly.

The events in the plugin (CodeCompanionRequestFinished) alongside require("codecompanion").buf_get_chat(bufnr) would allow you to manage messages and delete pinned references yourself. I may need to make it easier detect a pin from the messages table but that could be an option.

[GitMurf]

The events in the plugin (CodeCompanionRequestFinished) alongside require("codecompanion").buf_get_chat(bufnr) would allow you to manage messages and delete pinned references yourself. I may need to make it easier detect a pin from the messages table but that could be an option.

See my most recent message above. To your point, I actually got what I needed for deleting messages by creating a custom keymap and using the provided Chat param to get messages and then able to get reference ID from chat message if has reference and then can get a reference from its ID by using Chat.References and then check if ref is pinned by looking at ref.opts.pinned == true... on my phone right now so this is off top of my head but mostly accurate ;)

As described above, my only issue I am still facing is figuring out how to "reload" / "refresh" the chat buffer to account for deleted messages (when deleting other messages because references are typically set to visible false so no need to refresh chat buffer... but for deleting a bad partial message for example when Claude API craps out in middle as an example) to remove them from chat buffer (and make sure all the extmarks are updated accordingly).

[olimorris]

I've just added CodeCompanionChatPin as an event. Every time a pinned reference is refreshed, this fires and includes the chat buffer number alongside the ID of the reference.

[bassamsdata]

@bassamsdata sounds great! If you want a tester or any help or review, let me know!

Hey @GitMurf, I’ve been working on PR #610 for the past week and it’s now in the final stages. I’d like to know if you’d be able to test it out. It’s not completely finished yet, but I’m trying to figure out the best style to send it to the LLM.