feat(api): add /commands to show user commands

Author: cameronr

lua/opencode/api.lua

@@ -395,7 +395,7 @@ function M.select_agent()
 end
 
 function M.switch_mode()
-  local modes = require('opencode.config_file').get_opencode_agents()
+  local modes = require('opencode.config_file').get_opencode_agents() --[[@as string[] ]]
 
   local current_index = util.index_of(modes, state.current_mode)
 
@@ -519,6 +519,33 @@ function M.mcp()
   ui.render_lines(msg)
 end
 
+function M.commands_list()
+  local info = require('opencode.config_file')
+  local commands = info.get_user_commands()
+  if not commands then
+    vim.notify('No user commands found. Please check your opencode config file.', vim.log.levels.WARN)
+    return
+  end
+
+  state.display_route = '/commands'
+  M.open_input()
+
+  local msg = M.with_header({
+    '### Available User Commands',
+    '',
+    '| Name | Description |',
+    '|------|-------------|',
+  })
+
+  for name, def in pairs(commands) do
+    local desc = def.description or ''
+    table.insert(msg, string.format('| %s | %s |', name, desc))
+  end
+
+  table.insert(msg, '')
+  ui.render_lines(msg)
+end
+
 --- Runs a user-defined command by name.
 --- @param name string The name of the user command to run.
 --- @param args? string[] Additional arguments to pass to the command.
@@ -1015,6 +1042,11 @@ M.commands = {
     fn = M.mcp,
   },
 
+  commands_list = {
+    desc = 'Show user-defined commands',
+    fn = M.commands_list,
+  },
+
   permission = {
     desc = 'Respond to permissions (accept/accept_all/deny)',
     completions = { 'accept', 'accept_all', 'deny' },
@@ -1039,6 +1071,7 @@ M.slash_commands_map = {
   ['/agent'] = { fn = M.select_agent, desc = 'Select agent mode' },
   ['/agents_init'] = { fn = M.initialize, desc = 'Initialize AGENTS.md session' },
   ['/child-sessions'] = { fn = M.select_child_session, desc = 'Select child session' },
+  ['/commands'] = { fn = M.commands_list, desc = 'Show user-defined commands' },
   ['/compact'] = { fn = M.compact_session, desc = 'Compact current session' },
   ['/mcp'] = { fn = M.mcp, desc = 'Show MCP server configuration' },
   ['/models'] = { fn = M.configure_provider, desc = 'Switch provider/model' },

lua/opencode/core.lua

@@ -277,7 +277,7 @@ local function on_opencode_server()
 end
 
 --- Switches the current mode to the specified agent.
---- @param mode string The agent/mode to switch to
+--- @param mode string|nil The agent/mode to switch to
 --- @return boolean success Returns true if the mode was switched successfully, false otherwise
 function M.switch_to_mode(mode)
   if not mode or mode == '' then

tests/unit/api_spec.lua

@@ -276,4 +276,62 @@ describe('opencode.api', function()
       notify_stub:revert()
     end)
   end)
+
+  describe('/commands command', function()
+    it('displays user commands when available', function()
+      local config_file = require('opencode.config_file')
+      local original_get_user_commands = config_file.get_user_commands
+
+      config_file.get_user_commands = function()
+        return {
+          ['build'] = { description = 'Build the project' },
+          ['test'] = { description = 'Run tests' },
+          ['deploy'] = { description = 'Deploy to production' },
+        }
+      end
+
+      stub(ui, 'render_lines')
+      stub(api, 'open_input')
+
+      api.commands_list()
+
+      assert.stub(api.open_input).was_called()
+      assert.stub(ui.render_lines).was_called()
+
+      local render_args = ui.render_lines.calls[1].refs[1]
+      local rendered_text = table.concat(render_args, '\n')
+
+      assert.truthy(rendered_text:match('Available User Commands'))
+      assert.truthy(rendered_text:match('Description'))
+      assert.truthy(rendered_text:match('build'))
+      assert.truthy(rendered_text:match('Build the project'))
+      assert.truthy(rendered_text:match('test'))
+      assert.truthy(rendered_text:match('Run tests'))
+      assert.truthy(rendered_text:match('deploy'))
+      assert.truthy(rendered_text:match('Deploy to production'))
+
+      config_file.get_user_commands = original_get_user_commands
+    end)
+
+    it('shows warning when no user commands exist', function()
+      local config_file = require('opencode.config_file')
+      local original_get_user_commands = config_file.get_user_commands
+
+      config_file.get_user_commands = function()
+        return nil
+      end
+
+      local notify_stub = stub(vim, 'notify')
+
+      api.commands_list()
+
+      assert.stub(notify_stub).was_called_with(
+        'No user commands found. Please check your opencode config file.',
+        vim.log.levels.WARN
+      )
+
+      config_file.get_user_commands = original_get_user_commands
+      notify_stub:revert()
+    end)
+  end)
 end)