New in v11.14.0 - ✨ Workspace slash command

[olimorris]

"Whilst LLMs are incredibly powerful, they have no knowledge of the architectural decisions yourself or your team have made on a project. They have no context as to why you've selected the dependencies that you have. And, they can't see how your codebase has evolved over time." (extract from the docs)

The new workspace slash command allows users to share defined groups of files and/or symbols with an LLM, alongside some pre-written context. Think of it as a context management system

Background

For as long as I can remember on this project, I've wanted to add the ability for users to share their workspace with an LLM. That is, to be able to share their project/repo files and have a direct conversation about them. Alas, there were many things that I needed to figure out and implement before I could (91adfac, 767efee, 9c41484 and whatever the commit hashes are for the chat buffer messages table).

The @workspace tool in Copilot Chat served as the initial inspiration but over time I found it to be near ineffective. To get any real output from Copilot you need to send copious amounts of context over and it will never understand the technical and architectural decisions that you made in your project.

As I approached the start of this year, I began to think deeply about how I'd support workspaces in the plugin. I toyed with the idea of having a frecency algorithm coupled with a project hierarchy function to understand how files were structured and how they were being used across the repo. But soon remembered algorithms ≠ context. And my biggest learning of working with LLMs for around 18+ months (both professionally and personally) is that the quality of the context is directly proportional to the quality of the output.

So it was somewhat fortuitous that I came across an amazing blog post entitled "The day I taught AI to read code like a Senior Developer" at the start of January. The long and the short of it:

"We’d been teaching AI to read code like a fresh bootcamp grad, not a senior developer"

and as a result:

"Instead of dumping files linearly, we built a context-aware grouping system"

...that was the spark I needed to define the end goal and implement the workspace slash command.

How it works

The plugin uses a codecompanion-workspace.json file in the root of the current working directory. This groups files together with the output being the complete file or the symbolic outline of the file, surrounded by context that the user has defined themselves (...or perhaps asked an LLM to write part of). This combination is then shared with the LLM. The slash command will iterate through each file in the files or symbols array adding them sequentially.

You can see an example here. Although please note, I'll be tweaking this significantly over the coming days. I've released this feature a little earlier than planned so I can start using it to solve some current open issues.

Usage

• Read the docs, both here and here
• Build a codecompanion-workspace.json file in the root of your current working directory
• In the chat buffer use the /workspace command and select a group
• Investigate the context in the chat buffer with gd

Managing expectations

Whilst I have no evidence for this, I suspect that most users would have expected and wanted a command to automatically feed relevant files into the chat buffer, perhaps with some added context. For those that still think that, I'd ask them to read the blog post and align to their experiences of coding with LLMs. Failing that, it's relatively easy to load files into a chat buffer, programmatically with Lua (#641).

Other points to note

• I've added symbol support for C, C++, Go, JavaScript, PHP, Rust, TypeScript, Vim (alongside Python, Ruby and Lua)
• For any missing filetypes, if you're familiar with Tree-sitter queries, these should be pretty trivial to PR
• The symbols queries now fetch imports and the start and end line numbers for any matches to give output like:

local symbols = {
    "- import: `from .helper import Helper` (from line 1 to 1)",
    "- import: `from .utilities.logger import Logger` (from line 2 to 2)",
    "- class: `DummyClass` (from line 4 to 11)",
    "- function: `__init__` (from line 5 to 7)",
    "- function: `sample_method` (from line 9 to 11)",
}

• The @files tool has a read_lines method to be able to get the content between two line numbers (ideal for expanding on symbols)

Future plans

I intend to expand support beyond files and symbols to URLs and possibly help tags. I am very keen to be able to send over a curated list of git commits with changes, so the LLM has context around how changes are made to projects. Alongside building a tool to send over the full project structure.

Conclusion

As always, thanks for the consistently great ideas and support on the plugin.

[SDGLBL]

Currently, I have implemented a similar context management mechanism toy for myself, with the primary goal of providing more comprehensive context for inline completions. Overall, it leverages the telescope plugin to allow users to bind other files that the current file depends on, enabling file context awareness. This ensures that the model can see sufficient dependency context when performing inline completions in the current file. For various languages, this implementation can parse the import statements at the beginning of each file to determine which files need to be imported. It also allows referencing user-specified dependency files and then solidifies them into a "current_file 2 group files context" format. I believe that the concept of "group" mentioned in workfspace could also adopt this approach in long-term planning. For a project, we could maintain a group files context for each buffer or each file it depends on. To reduce complexity, regular expression matching could be supported to ensure that certain types of files share the same group files context. This would guarantee that the model has access to optimal contextual dependencies for every task performed on any given file within a project.

So, in the long-term plan, perhaps we can add features like these:

1. Use telescope to allow users to quickly bind other files that the current file depends on, and solidify them into the current file's group.
2. By default, inline can utilize the group bound to the current file while also being able to use other groups.
3. Additionally, users can specify which groups they need to depend on (via the already provided workspace command)

[GitMurf]

Wow @olimorris your vision and perspective could not align more with my own if I tried! This is so amazing! I was just thinking a couple days ago about implementing my own version of something very similar to this feature! Now I don't have to ;)

My initial thoughts on "next iterations" of this feature:

A way to create, modify, add, remove to a Group in the app (thinking just like the /files with Telescope where you can select multiple files to add as references... we could similarly select multiple files to add to a Group that is stored in the workspace json. And then to modify a group could similarly show with telescope all the files as part of the group and then can select items to remove (as an example).

Amazing work as usual!

[olimorris]

In v11.22.0 I've now added support for URLs. More here.

[niclas-j]

@olimorris I think something less manual would be nice. I think cursor in composer currently runs a grep for certain keywords and includes those relevant files into the context. That’s what I would expect from a workspace command.

[olimorris]

I think it comes down to what you intend to do with your workspace. Do you really find you get great outcomes by sending a bunch of files over to an LLM that are linked by keywords? Surely you have to explain the context and the decisions you made and what your goals are?

My favourite quote from that post which continues to resonate with me:

Making code suggestions without deep context is like having a brilliant junior dev who just joined yesterday - they’ll write clean code that subtly breaks everything.

I have some ideas to make it less manual but there's still no way for an LLM to know why you and your team made the decisions that you did. Or, what you want to accomplish/aim for.

[melodyogonna]

This is a feature I've been looking for for some time, thank you. I'm sure the user experience can be improved as time goes on.
for example, I have a hypothesis that big codebase features are grouped by packages - all the files in a directory work towards the same final functionality. If that is the case, you don't need to feed an LLM the files in a package one after the other (like in the files array). The package can be one unit, like Go packages, and you just have to provide context about what the package is supposed to do, rather than what the package and every file in it is supposed to do. LLMs can pick file-specific context from documentation inside each file.

[fredrikaverpil]

@olimorris I'm wondering if something's up with the vars. This does not work:

{
  "name": "CodeCompanion.nvim",
  "version": "1.0.0",
  "workspace_spec": "1.0",
  "description": "An example workspace file",
  "system_prompt": "CodeCompanion.nvim is an AI-powered productivity tool...",
  "vars": {
    "plugin_dir": "lua/godoc"
  },
  "groups": [
    {
      "name": "Neovim Plugin",
      "system_prompt": "Help developing the plugin and its features",
      "opts": {
        "remove_config_system_prompt": true
      },
      "files": [
        {
          "description": "Installation and usage instructions",
          "path": "README.md"
        },
        {
          "description": "Entry point of Neovim plugin",
          "path": "${plugin_dir}/init.lua"
        }
      ]
    }
  ]
}

I get the following error:

[WARN] 2025-03-08 15:04:06 Could not read the file: ${plugin_dir}/init.lua

But if I make this change, it works fine:

-          "path": "${plugin_dir}/init.lua"
+          "path": "lua/godoc/init.lua"

Do you see this on your end too?
I'm following the current docs and I'm on macOS, Neovim v0.11.0 nightly.

Furthermore, what do you think about making it possible to define a glob for files?
Maybe something like;

"files": [
	{
	  "description": "Documentation files",
	  "path": "docs/**/*.md"
	}
]

[olimorris]

They need to be the group level, as per the documentation

[fredrikaverpil]

Ah, thank you - I somehow missed that the two examples had to be combined to be valid.

[mhuggins7278]

I must being missing this is the docs. I can't get the globs working

[fredrikaverpil]

@mhuggins7278 you need to combine the two examples. Put the second snippet into the first one.

Globals, that is. Globs I don't think are supported.