Proposal: Dynamic placeholder substitution in Chat Interactions ($ARGUMENTS, $1, etc.)

[viespejo]

Motivation

Currently, when using Chat Interactions (user_prompt: true), user input from vim.ui.input is always appended as a new message at the end of the messages table. While this works for simple prompts, it limits the ability to create complex "templates" where the user's input needs to be injected into a specific part of a pre-defined system or user prompt.

I'm proposing a way to use placeholders within the interaction's messages to allow for more flexible templating.
It is similar to how Claude Code uses parameters in slash commands.

Proposed Change

The idea is to scan the existing messages for specific placeholders and replace them with the user's input:

• $ARGUMENTS: Replaces with the full input string.
• $1, $2, etc.: Replaces with specific positional words from the input.

Key Logic:

1. If placeholders are found in any message, they are substituted.
2. If no placeholders are detected, the logic falls back to the current behavior (appending the input as a new message). This ensures backward compatibility.

Example Usage

With this change, a user could define a prompt like this:

---
name: Github Issue
interaction: chat
description: Pull and fix a GitHub issue
opts:
  alias: gh-issue
  auto_submit: true
  is_slash_cmd: true
  ignore_system_prompt: true
  stop_context_insertion: true
  user_prompt: true
---

## system

Please analyze and fix the GitHub issue: $ARGUMENTS.

Follow these steps:

1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.

## user

@{full_stack_dev}

You could then for example use /gh-issue and introduce 1234 to have CC fix issue 1234.

Implementation Details

We could create a process_arguments function to handle this within lua/codecompanion/interactions/init.lua:

local function process_arguments(messages, input)
  if not input or input == "" then
    return
  end

  -- positional arguments
  local args = {}
  for word in input:gmatch("%S+") do
    table.insert(args, word)
  end

  -- replacements map
  local replacements = {
    ["%$ARGUMENTS"] = input, -- Represents the full plural string
  }
  for i, val in ipairs(args) do
    replacements["%$" .. i] = val
  end

  local replaced_any = false

  -- iterate through existing messages to perform string substitution
  for _, message in ipairs(messages) do
    for pattern, replacement in pairs(replacements) do
      local new_content, n = message.content:gsub(pattern, replacement)
      if n > 0 then
        message.content = new_content
        replaced_any = true
      end
    end
  end

  -- if no placeholders were detected, treat the input as a new standalone prompt
  if not replaced_any then
    table.insert(messages, {
      role = config.constants.USER_ROLE,
      content = input,
    })
  end
end

and integrated it into the chat interaction flow:

function Interactions:chat()
  -- existing code...
  local function create_chat(input)
    if input then
      -- before: table.insert(messages, {
      --   role = config.constants.USER_ROLE,
      --   content = input,
      -- })
      process_arguments(messages, input)
    end
    -- rest of the function...
  end

  -- existing code...
end

@olimorris , I have searched for similar discussions in the repository and found none, so I believe this is a good opportunity to enhance the flexibility of chat interactions. Or maybe there is already a way to do this and I don't know about it.

[olimorris]

This is a cool idea, I just think it's too niche for me to merge. I'm looking at ways I can support these types of ideas without committing them into main. So open for ideas on that.

[viespejo]

This is a great point about keeping the core clean and general.
But in this specific case, I believe it sits at the edge of "niche" since it seems to be the standard in other similar tools:

• Claude Code: https://code.claude.com/docs/en/slash-commands#arguments
• Gemini CLI: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/custom-commands.md#handling-arguments
• Codex: https://developers.openai.com/codex/custom-prompts

To address this, I'd pivot the proposal from a hardcoded feature to a general-purpose hook, allowing users to implement placeholders (or any other input transformation) without bloating the core.

By adding a resolve_input hook to the global chat configuration.

Proposed Implementation

I suggest adding resolve_input to interactions.chat.opts.

In lua/codecompanion/config.lua:

-- ...existing code...
      opts = {
        blank_prompt = "", -- The prompt to use when the user doesn't provide a prompt
-- ...existing code...
        ---@param ctx CodeCompanion.SystemPrompt.Context
        ---@return string
        system_prompt = function(ctx)
-- ...existing code...
            )
        end,
        ---Function to resolve user input from vim.ui.input into the messages
        ---@param messages table List of message objects {role: string, content: string}
        ---@param input string|nil The raw string retrieved from vim.ui.input
        resolve_input = function(messages, input)
          if not input or input == "" then
            return
          end
          table.insert(messages, {
            role = constants.USER_ROLE,
            content = input,
          })
        end,
      },
-- ...existing code...

In lua/codecompanion/interactions/init.lua:

-- ...existing code...
  local function create_chat(input)
    if input then
      if type(config.interactions.chat.opts.resolve_input) == "function" then
        config.interactions.chat.opts.resolve_input(messages, input)
      end
    end

    if type(opts.pre_hook) == "function" then
-- ...existing code...

User-Land Example: Placeholder Substitution

With this hook, a user can easily implement the positional arguments logic in their own configuration:

local cc_config = require("codecompanion.config")
local original_resolve_input = cc_config.interactions.chat.opts.resolve_input

require("codecompanion").setup({
  interactions = {
    chat = {
      opts = {
        resolve_input = function(messages, input)
          if not input or input == "" then
            return
          end

          -- positional arguments
          local args = {}
          for word in input:gmatch("%S+") do
            table.insert(args, word)
          end

          -- replacements map
          local replacements = {
            ["%$ARGUMENTS"] = input, -- Represents the full plural string
          }
          for i, val in ipairs(args) do
            replacements["%$" .. i] = val
          end

          local replaced_any = false

          -- iterate through existing messages to perform string substitution
          for _, message in ipairs(messages) do
            for pattern, replacement in pairs(replacements) do
              local new_content, n = message.content:gsub(pattern, replacement)
              if n > 0 then
                message.content = new_content
                replaced_any = true
              end
            end
          end

          -- if no placeholders were detected, fall back to default behavior
          if not replaced_any then
            original_resolve_input(messages, input)
          end
        end,
      },
    },
  },
})