brainiac 0.0.6 → 0.0.8

data/bin/brainiac

@@ -1,5 +1,6 @@
 #!/usr/bin/env ruby
 
+require "English"
 require "json"
 require "optparse"
 require "fileutils"
@@ -49,6 +50,21 @@ def save_config(config)
   File.write(CONFIG_FILE, JSON.pretty_generate(config))
 end
 
+# Resolve the default agent name: env var → brainiac.json → nil.
+def default_agent_name
+  return ENV["AI_AGENT_NAME"] if ENV["AI_AGENT_NAME"] && !ENV["AI_AGENT_NAME"].empty?
+
+  brainiac_config_path = File.join(BRAINIAC_DIR, "brainiac.json")
+  if File.exist?(brainiac_config_path)
+    config = JSON.parse(File.read(brainiac_config_path))
+    return config["default_agent"] if config["default_agent"]
+  end
+
+  nil
+rescue JSON::ParserError
+  nil
+end
+
 def find_server_pid
   # First check PID file
   if File.exist?(PID_FILE)
@@ -187,6 +203,23 @@ def stop_server
   end
 end
 
+def update_handler_config(name, enabled)
+  brainiac_config_path = File.join(BRAINIAC_DIR, "brainiac.json")
+  config = if File.exist?(brainiac_config_path)
+             JSON.parse(File.read(brainiac_config_path))
+           else
+             {}
+           end
+
+  config["handlers"] ||= {}
+  config["handlers"][name] = enabled
+  File.write(brainiac_config_path, JSON.pretty_generate(config))
+
+  action = enabled ? "enabled" : "disabled"
+  puts "✓ Handler '#{name}' #{action}"
+  puts "  Restart the server for changes to take effect: brainiac restart"
+end
+
 def start_server(daemon: false)
   # Resolve the real path of the brainiac script (follows symlinks)
   receiver_path = File.join(BRAINIAC_ROOT, "receiver.rb")
@@ -294,9 +327,9 @@ def register_project(options)
     exit 1
   end
 
-  print "Fizzy tags (comma-separated) [#{project_key}]: "
+  print "Tags (comma-separated) [#{project_key}]: "
   tags_input = $stdin.gets.chomp
-  fizzy_tags = tags_input.empty? ? [project_key] : tags_input.split(",").map(&:strip)
+  project_tags = tags_input.empty? ? [project_key] : tags_input.split(",").map(&:strip)
 
   print "GitHub repo [#{info["github_repo"]}]: "
   github_repo = $stdin.gets.chomp
@@ -310,15 +343,24 @@ def register_project(options)
   agent_model = $stdin.gets.chomp
   agent_model = "auto" if agent_model.empty?
 
-  default_agent_name = ENV.fetch("AI_AGENT_NAME", "Galen")
-  print "Agent name [#{default_agent_name}]: "
-  agent_name = $stdin.gets.chomp
-  agent_name = default_agent_name if agent_name.empty?
+  agent_default = default_agent_name
+  if agent_default
+    print "Agent name [#{agent_default}]: "
+    agent_name = $stdin.gets.chomp
+    agent_name = agent_default if agent_name.empty?
+  else
+    print "Agent name: "
+    agent_name = $stdin.gets.chomp
+    if agent_name.empty?
+      puts "Error: No default agent configured. Provide a name or run 'brainiac agent default <name>' first."
+      exit 1
+    end
+  end
 
   # Build project config
   project_config = {
     "repo_path" => info["repo_path"],
-    "fizzy_tags" => fizzy_tags,
+    "tags" => project_tags,
     "github_repo" => github_repo,
     "agent_name" => agent_name,
     "agent_model" => agent_model,
@@ -331,7 +373,7 @@ def register_project(options)
   puts
   puts "✓ Project '#{project_key}' registered successfully!"
   puts "  Repo: #{info["repo_path"]}"
-  puts "  Tags: #{fizzy_tags.join(", ")}"
+  puts "  Tags: #{project_tags.join(", ")}"
   puts "  GitHub: #{github_repo}" if github_repo
 end
 
@@ -365,7 +407,7 @@ def list_projects
     default_marker = config["default"] ? " (default)" : ""
     puts "  #{key}#{default_marker}"
     puts "    Path: #{config["repo_path"]}"
-    puts "    Tags: #{config["fizzy_tags"].join(", ")}"
+    puts "    Tags: #{config["tags"] || config["project_tags"].join(", ")}"
     puts "    GitHub: #{config["github_repo"]}" if config["github_repo"]
     puts "    Agent: #{config["agent_cli"]} (model: #{config["agent_model"]})"
     puts
@@ -524,7 +566,7 @@ def brain_search(query, scope: :knowledge, agent_name: nil)
 
   collection = case scope
                when :persona
-                 agent_name ||= ENV.fetch("AI_AGENT_NAME", "Galen")
+                 agent_name ||= default_agent_name || "agent"
                  persona_collection_for(agent_name)
                else
                  KNOWLEDGE_COLLECTION
@@ -611,6 +653,52 @@ when "setup"
     puts "✓ Copied #{copied} example config(s) to ~/.brainiac/ (existing files preserved)"
   end
 
+  # Copy CLI provider examples
+  providers_dir = File.join(BRAINIAC_DIR, "cli-providers")
+  FileUtils.mkdir_p(providers_dir)
+  providers_src = File.join(BRAINIAC_ROOT, "templates", "cli-providers")
+  if Dir.exist?(providers_src)
+    Dir.glob(File.join(providers_src, "*.example")).each do |template|
+      dest = File.join(providers_dir, File.basename(template, ".example"))
+      FileUtils.cp(template, dest) unless File.exist?(dest)
+    end
+  end
+
+  # Handler configuration
+  brainiac_config_path = File.join(BRAINIAC_DIR, "brainiac.json")
+  puts ""
+  if File.exist?(brainiac_config_path)
+    puts "✓ Handler config already exists at ~/.brainiac/brainiac.json"
+  else
+    puts "Which integrations do you want to enable?"
+    puts "(You can change this later in ~/.brainiac/brainiac.json)"
+    puts ""
+
+    available_handlers = {
+
+      "github" => "GitHub (PR reviews, CI failure handling, deploy tracking)",
+      "discord" => "Discord (conversational agent access via bot)",
+      "zoho" => "Zoho Mail (email notifications and triage)"
+    }
+
+    enabled_handlers = {}
+    available_handlers.each do |key, description|
+      print "  Enable #{description}? [Y/n] "
+      answer = $stdin.gets&.strip&.downcase
+      enabled_handlers[key] = answer != "n"
+    end
+
+    config = { "handlers" => enabled_handlers }
+    File.write(brainiac_config_path, JSON.pretty_generate(config))
+    puts ""
+    puts "✓ Wrote handler config to ~/.brainiac/brainiac.json"
+
+    enabled_list = enabled_handlers.select { |_, v| v }.keys
+    disabled_list = enabled_handlers.reject { |_, v| v }.keys
+    puts "  Enabled: #{enabled_list.join(", ")}" if enabled_list.any?
+    puts "  Disabled: #{disabled_list.join(", ")}" if disabled_list.any?
+  end
+
   puts ""
   puts "Next steps:"
   puts "  1. Edit config files in ~/.brainiac/ with your secrets and IDs"
@@ -684,6 +772,64 @@ when "show"
   end
   show_project(ARGV[0])
 
+when "handler", "handlers"
+  handler_cmd = ARGV.shift
+  case handler_cmd
+  when "list", "ls", nil
+    brainiac_config_path = File.join(BRAINIAC_DIR, "brainiac.json")
+    config = if File.exist?(brainiac_config_path)
+               JSON.parse(File.read(brainiac_config_path))
+             else
+               {}
+             end
+    handlers = config["handlers"] || {}
+
+    # Built-in handlers
+    builtins = %w[github discord zoho]
+    puts "Built-in handlers:"
+    builtins.each do |name|
+      enabled = handlers.fetch(name, true)
+      status = enabled ? "✓ enabled" : "✗ disabled"
+      puts "  #{name.ljust(10)} #{status}"
+    end
+
+    # Custom handlers
+    custom_dir = File.join(BRAINIAC_DIR, "handlers")
+    if Dir.exist?(custom_dir)
+      custom_files = Dir.glob(File.join(custom_dir, "*.rb"))
+      if custom_files.any?
+        puts ""
+        puts "Custom handlers (#{custom_dir}):"
+        custom_files.each do |f|
+          name = File.basename(f, ".rb")
+          enabled = handlers.fetch(name, true)
+          status = enabled ? "✓ enabled" : "✗ disabled"
+          puts "  #{name.ljust(10)} #{status}"
+        end
+      end
+    end
+
+  when "enable"
+    name = ARGV.shift
+    unless name
+      puts "Usage: brainiac handler enable <name>"
+      exit 1
+    end
+    update_handler_config(name, true)
+
+  when "disable"
+    name = ARGV.shift
+    unless name
+      puts "Usage: brainiac handler disable <name>"
+      exit 1
+    end
+    update_handler_config(name, false)
+
+  else
+    puts "Usage: brainiac handler <list|enable|disable> [name]"
+    exit 1
+  end
+
 when "config"
   OptionParser.new do |opts|
     opts.banner = "Usage: brainiac config [options]"
@@ -853,7 +999,7 @@ when "discord"
     else
       puts "Agents with Discord bots:"
       agents_with_tokens.each do |key, entry|
-        display = entry["fizzy_name"] || key.capitalize
+        display = entry["display_name"] || key.capitalize
         token = entry.dig("env", "DISCORD_BOT_TOKEN") || entry["discord_bot_token"]
         token_preview = "#{token[0..10]}..."
         puts "  #{display} (#{key}): #{token_preview}"
@@ -909,31 +1055,31 @@ when "discord"
     HELP
   end
 
-when "card-map"
-  card_map_file = File.join(BRAINIAC_DIR, "card_map.json")
+when "work-items", "card-map"
+  work_items_file = File.join(BRAINIAC_DIR, "work_items.json")
   cm_cmd = ARGV.shift
   case cm_cmd
   when "clean"
-    unless File.exist?(card_map_file)
-      puts "No card_map.json found."
+    unless File.exist?(work_items_file)
+      puts "No work items found."
       exit 0
     end
-    map = JSON.parse(File.read(card_map_file))
+    map = JSON.parse(File.read(work_items_file))
     before = map.size
     # Remove entries with no valid worktree on disk
     map.reject! { |_id, info| info["worktree"].nil? || !File.directory?(info["worktree"].to_s) }
     after = map.size
     removed = before - after
-    File.write(card_map_file, JSON.pretty_generate(map))
-    puts "Cleaned card map: removed #{removed} stale entries (#{before} → #{after})"
+    File.write(work_items_file, JSON.pretty_generate(map))
+    puts "Cleaned work items: removed #{removed} stale entries (#{before} → #{after})"
   when "list", "ls", nil
-    unless File.exist?(card_map_file)
-      puts "No card_map.json found."
+    unless File.exist?(work_items_file)
+      puts "No work items found."
       exit 0
     end
-    map = JSON.parse(File.read(card_map_file))
+    map = JSON.parse(File.read(work_items_file))
     if map.empty?
-      puts "Card map is empty."
+      puts "No active work items."
     else
       map.each_value do |info|
         num = info["number"] ? "##{info["number"]}" : "(no number)"
@@ -943,7 +1089,7 @@ when "card-map"
       end
     end
   else
-    puts "Usage: brainiac card-map [clean|list]"
+    puts "Usage: brainiac work-items [clean|list]"
     puts "  clean   Remove stale entries (missing worktrees)"
     puts "  list    Show all card map entries"
   end
@@ -952,14 +1098,24 @@ when "brain"
   brain_cmd = ARGV.shift
   case brain_cmd
   when "init"
-    agent = ARGV[0] || ENV.fetch("AI_AGENT_NAME", "Galen")
+    agent = ARGV[0] || default_agent_name
+    unless agent
+      puts "Usage: brainiac brain init <agent-name>"
+      puts "  Or set a default: brainiac agent default <name>"
+      exit 1
+    end
     brain_init(agent)
   when "status", "show"
-    agent = ARGV[0] || ENV.fetch("AI_AGENT_NAME", "Galen")
+    agent = ARGV[0] || default_agent_name
+    unless agent
+      puts "Usage: brainiac brain status <agent-name>"
+      puts "  Or set a default: brainiac agent default <name>"
+      exit 1
+    end
     brain_status(agent)
   when "search", "query"
     scope = :knowledge
-    agent_name = ENV.fetch("AI_AGENT_NAME", "Galen")
+    agent_name = default_agent_name
     if ARGV.include?("--persona")
       ARGV.delete("--persona")
       scope = :persona
@@ -979,7 +1135,11 @@ when "brain"
   when "path"
     what = ARGV[0]
     if what == "persona"
-      agent = ARGV[1] || ENV.fetch("AI_AGENT_NAME", "Galen")
+      agent = ARGV[1] || default_agent_name
+      unless agent
+        puts "Usage: brainiac brain path persona <agent-name>"
+        exit 1
+      end
       puts persona_dir_for(agent)
     else
       puts KNOWLEDGE_DIR
@@ -1021,7 +1181,7 @@ when "cron"
   when "add", "create"
     # Parse arguments
     schedule = nil
-    agent = ENV.fetch("AI_AGENT_NAME", "Galen")
+    agent = default_agent_name
     project = nil
     model = nil
     effort = nil
@@ -1402,11 +1562,15 @@ when "agent"
   case agent_cmd
   when "list", "ls"
     registry = File.exist?(agent_registry_file) ? JSON.parse(File.read(agent_registry_file)) : {}
+
+    # Determine current default agent
+    default_agent = default_agent_name
+
     if registry.empty?
       puts "No agents in registry."
     else
       agents = registry.select { |_, e| e.is_a?(Hash) }.map do |key, entry|
-        display = entry["fizzy_name"] || key.capitalize
+        display = entry["display_name"] || key.capitalize
         details = []
         if entry["role"]
           roles = Array(entry["role"])
@@ -1414,13 +1578,15 @@ when "agent"
         end
         details << "cli:#{entry["cli_provider"]}" if entry["cli_provider"]
         details << "env:#{entry["env"].size}" if entry["env"]&.any?
-        { key: key, display: display, local: entry["local"], details: details.join(" | ") }
+        is_default = default_agent && display.downcase == default_agent.downcase
+        { key: key, display: display, local: entry["local"], details: details.join(" | "), default: is_default }
       end
 
       local, remote = agents.partition { |a| a[:local] }
 
       local.each do |a|
         line = "  #{a[:display]} (#{a[:key]})"
+        line += "  ★ default" if a[:default]
         line += "  #{a[:details]}" unless a[:details].empty?
         puts line
       end
@@ -1430,12 +1596,51 @@ when "agent"
         puts "  Remote:" if local.any?
         remote.each do |a|
           line = "  #{a[:display]} (#{a[:key]})"
+          line += "  ★ default" if a[:default]
           line += "  #{a[:details]}" unless a[:details].empty?
           puts line
         end
       end
     end
 
+  when "default"
+    brainiac_config_path = File.join(BRAINIAC_DIR, "brainiac.json")
+    brainiac_config = File.exist?(brainiac_config_path) ? JSON.parse(File.read(brainiac_config_path)) : {}
+    name = ARGV.shift
+
+    if name
+      # Set default agent
+      registry = File.exist?(agent_registry_file) ? JSON.parse(File.read(agent_registry_file)) : {}
+      agent_key = name.downcase.gsub(/[^a-z0-9-]/, "-")
+
+      # Resolve display name from registry if it exists
+      display_name = if registry.dig(agent_key, "display_name")
+                       registry[agent_key]["display_name"]
+                     else
+                       name
+                     end
+
+      brainiac_config["default_agent"] = display_name
+      ensure_brainiac_dir
+      File.write(brainiac_config_path, JSON.pretty_generate(brainiac_config))
+      puts "✓ Default agent set to '#{display_name}'"
+    else
+      # Show current default
+      env_override = ENV.fetch("AI_AGENT_NAME", nil)
+      config_default = brainiac_config["default_agent"]
+
+      if env_override
+        puts "Default agent: #{env_override} (from AI_AGENT_NAME env var)"
+        puts "  Config value: #{config_default}" if config_default && config_default != env_override
+      elsif config_default
+        puts "Default agent: #{config_default}"
+      else
+        puts "No default agent configured."
+        puts "Set one with: brainiac agent default <name>"
+        puts "  Or set AI_AGENT_NAME in your environment."
+      end
+    end
+
   when "create", "add"
     name = ARGV.shift
     unless name
@@ -1520,7 +1725,7 @@ when "agent"
       persona_text = input.empty? ? nil : input
     end
 
-    entry = { "fizzy_name" => name }
+    entry = { "display_name" => name }
     entry["local"] = true if local
     entry["cli_provider"] = cli_provider if cli_provider
     entry["role"] = roles.size == 1 ? roles.first : roles if roles.any?
@@ -1571,7 +1776,7 @@ when "agent"
       exit 1
     end
 
-    display = registry[agent_key]["fizzy_name"] || name
+    display = registry[agent_key]["display_name"] || name
     registry.delete(agent_key)
     File.write(agent_registry_file, JSON.pretty_generate(registry))
     puts "✓ Removed agent '#{display}' (#{agent_key}) from registry"
@@ -1581,15 +1786,17 @@ when "agent"
     puts <<~HELP
       Usage: brainiac agent <name> <command> [args]
              brainiac agent list
+             brainiac agent default [name]
              brainiac agent create <name> [options]
              brainiac agent remove <name>
 
       Commands:
         list                              List all agents in the registry
+        default [name]                    Show or set the default agent
         create <name> [options]           Add a new agent to the registry
         remove <name>                     Remove an agent from the registry
         <name> show                       Show agent configuration (tokens redacted)
-        <name> set <field> <value>        Update a config field (local, cli, role, persona, fizzy_name)
+        <name> set <field> <value>        Update a config field (local, cli, role, persona, display_name)
         <name> env <KEY> <VALUE>          Set an env var for an agent
         <name> env                        List env vars for an agent
         <name> env --delete <KEY>         Remove an env var from an agent
@@ -1601,6 +1808,8 @@ when "agent"
         --persona <text>     Create a persona style file
 
       Examples:
+        brainiac agent list
+        brainiac agent default Galen
         brainiac agent create SecurityBot --local --role code-reviewer
         brainiac agent create Jane --cli grok
         brainiac agent create MyAgent             # interactive mode
@@ -1608,7 +1817,7 @@ when "agent"
         brainiac agent galen set local true
         brainiac agent galen set persona "Dry, sardonic"
         brainiac agent galen set role code-reviewer,general-engineer
-        brainiac agent galen env FIZZY_TOKEN fizzy_abc123
+        brainiac agent galen env MY_TOKEN abc123
         brainiac agent galen show
     HELP
 
@@ -1633,11 +1842,11 @@ when "agent"
       puts JSON.pretty_generate(display)
 
     when "env"
-      if ARGV[0] == "--delete"
+      if ["--delete", "unset", "delete", "rm"].include?(ARGV[0])
         ARGV.shift
         var_name = ARGV.shift
         unless var_name
-          puts "Usage: brainiac agent #{agent_cmd} env --delete <KEY>"
+          puts "Usage: brainiac agent #{agent_cmd} env unset <KEY>"
           exit 1
         end
         registry = File.exist?(agent_registry_file) ? JSON.parse(File.read(agent_registry_file)) : {}
@@ -1689,7 +1898,7 @@ when "agent"
         puts "  cli <provider>         Set CLI provider"
         puts "  role <roles>           Set roles (comma-separated, or 'none' to clear)"
         puts "  persona <text>         Set/update persona style file"
-        puts "  fizzy_name <name>      Set display name for Fizzy @mentions"
+        puts "  display_name <name>    Set display name for @mentions"
         exit 1
       end
 
@@ -1737,7 +1946,7 @@ when "agent"
         persona_dir = File.join(BRAINIAC_DIR, "brain", "persona", agent_key)
         FileUtils.mkdir_p(persona_dir)
         persona_file = File.join(persona_dir, "style.md")
-        display = registry[agent_key]["fizzy_name"] || agent_cmd.capitalize
+        display = registry[agent_key]["display_name"] || agent_cmd.capitalize
         File.write(persona_file, <<~MD)
           ---
           name: #{agent_key}-style
@@ -1748,17 +1957,17 @@ when "agent"
         MD
         puts "✓ Wrote persona to #{persona_file}"
 
-      when "fizzy_name"
+      when "display_name"
         unless value
-          puts "Usage: brainiac agent #{agent_cmd} set fizzy_name <name>"
+          puts "Usage: brainiac agent #{agent_cmd} set display_name <name>"
           exit 1
         end
-        registry[agent_key]["fizzy_name"] = value
+        registry[agent_key]["display_name"] = value
         File.write(agent_registry_file, JSON.pretty_generate(registry))
-        puts "✓ Set fizzy_name=#{value} for #{agent_cmd}"
+        puts "✓ Set display_name=#{value} for #{agent_cmd}"
 
       else
-        puts "Unknown field '#{field}'. Available: local, cli, role, persona, fizzy_name"
+        puts "Unknown field '#{field}'. Available: local, cli, role, persona, display_name"
         exit 1
       end
 
@@ -1793,7 +2002,7 @@ when "role"
         roles = entry["role"].is_a?(Array) ? entry["role"] : [entry["role"]]
         roles.each do |r|
           agent_roles[r] ||= []
-          agent_roles[r] << (entry["fizzy_name"] || key.capitalize)
+          agent_roles[r] << (entry["display_name"] || key.capitalize)
         end
       end
 
@@ -1936,6 +2145,217 @@ when "completions"
     puts File.read(completion_file)
   end
 
+when "install"
+  name = ARGV.shift
+  unless name
+    puts "Usage: brainiac install <plugin-name> [options]"
+    puts ""
+    puts "Installs a Brainiac plugin gem (brainiac-<name>) and registers it."
+    puts ""
+    puts "Options:"
+    puts "  --path <dir>       Use a local gem directory (for development/private gems)"
+    puts "  --version <ver>    Install a specific version from RubyGems"
+    puts ""
+    puts "Examples:"
+    puts "  brainiac install whatsapp                            # from RubyGems"
+    puts "  brainiac install fizzy --path ~/Code/brainiac-fizzy  # local dev"
+    puts "  brainiac install slack --version 0.2.0               # specific version"
+    puts ""
+    puts "After installing, restart the server: brainiac restart"
+    exit 1
+  end
+
+  # Strip "brainiac-" prefix if user includes it
+  name = name.sub(/^brainiac-/, "")
+  version = nil
+  local_path = nil
+
+  # Parse flags
+  while ARGV.any?
+    case ARGV[0]
+    when "--version", "-v"
+      ARGV.shift
+      version = ARGV.shift
+    when "--path", "-p"
+      ARGV.shift
+      local_path = File.expand_path(ARGV.shift || "")
+    else
+      break
+    end
+  end
+
+  plugins_file = File.join(BRAINIAC_DIR, "plugins.json")
+  plugins_config = if File.exist?(plugins_file)
+                     JSON.parse(File.read(plugins_file))
+                   else
+                     { "plugins" => [] }
+                   end
+
+  existing = (plugins_config["plugins"] || []).find { |p| (p.is_a?(Hash) ? p["name"] : p.to_s) == name }
+  if existing
+    puts "Plugin '#{name}' is already installed."
+    puts "  To reinstall: brainiac uninstall #{name} && brainiac install #{name}"
+    exit 0
+  end
+
+  gem_name = "brainiac-#{name}"
+
+  if local_path
+    # Local path mode — validate the directory and register without gem install
+    unless Dir.exist?(local_path)
+      puts "Error: Path does not exist: #{local_path}"
+      exit 1
+    end
+
+    entry_file = File.join(local_path, "lib", "brainiac-#{name}.rb")
+    unless File.exist?(entry_file)
+      puts "Error: Expected entry file not found: #{entry_file}"
+      puts "  Plugin gems must have lib/brainiac-<name>.rb"
+      exit 1
+    end
+
+    puts "Registering #{gem_name} from local path: #{local_path}"
+
+    plugins_config["plugins"] ||= []
+    entry = { "name" => name, "gem" => gem_name, "path" => local_path, "installed_at" => Time.now.iso8601 }
+    plugins_config["plugins"] << entry
+
+    ensure_brainiac_dir
+    File.write(plugins_file, JSON.pretty_generate(plugins_config))
+
+    update_handler_config(name, true)
+
+    puts ""
+    puts "✓ Registered plugin '#{name}' from #{local_path}"
+    puts "  Restart the server to activate: brainiac restart"
+    puts "  Note: Source changes take effect on next server restart."
+  else
+    # RubyGems mode
+    puts "Installing #{gem_name}..."
+
+    install_cmd = "gem install #{gem_name}"
+    install_cmd += " --version '#{version}'" if version
+
+    system(install_cmd)
+    unless $CHILD_STATUS.success?
+      puts ""
+      puts "Failed to install #{gem_name}."
+      puts "  Check that the gem exists: https://rubygems.org/gems/#{gem_name}"
+      exit 1
+    end
+
+    # Register in plugins.json
+    plugins_config["plugins"] ||= []
+    entry = { "name" => name, "gem" => gem_name, "installed_at" => Time.now.iso8601 }
+    entry["version"] = version if version
+    plugins_config["plugins"] << entry
+
+    ensure_brainiac_dir
+    File.write(plugins_file, JSON.pretty_generate(plugins_config))
+
+    # Enable the handler
+    update_handler_config(name, true)
+
+    puts ""
+    puts "✓ Installed plugin '#{name}' (#{gem_name})"
+    puts "  Restart the server to activate: brainiac restart"
+  end
+
+when "uninstall"
+  name = ARGV.shift
+  unless name
+    puts "Usage: brainiac uninstall <plugin-name>"
+    puts ""
+    puts "Removes a Brainiac plugin from the configuration."
+    puts "The gem itself remains installed (use 'gem uninstall brainiac-<name>' to fully remove)."
+    exit 1
+  end
+
+  name = name.sub(/^brainiac-/, "")
+  gem_name = "brainiac-#{name}"
+
+  plugins_file = File.join(BRAINIAC_DIR, "plugins.json")
+  unless File.exist?(plugins_file)
+    puts "Plugin '#{name}' is not installed (no plugins.json found)."
+    exit 1
+  end
+
+  plugins_config = JSON.parse(File.read(plugins_file))
+  found = (plugins_config["plugins"] || []).any? { |p| (p.is_a?(Hash) ? p["name"] : p.to_s) == name }
+
+  unless found
+    puts "Plugin '#{name}' is not installed."
+    exit 1
+  end
+
+  plugins_config["plugins"].reject! { |p| (p.is_a?(Hash) ? p["name"] : p.to_s) == name }
+  File.write(plugins_file, JSON.pretty_generate(plugins_config))
+
+  # Disable the handler
+  update_handler_config(name, false)
+
+  puts "✓ Removed plugin '#{name}' from Brainiac."
+  puts "  The gem #{gem_name} is still installed system-wide."
+  puts "  To fully remove: gem uninstall #{gem_name}"
+  puts "  Restart the server to apply: brainiac restart"
+
+when "plugins"
+  plugins_cmd = ARGV.shift
+
+  case plugins_cmd
+  when "list", "ls", nil
+    plugins_file = File.join(BRAINIAC_DIR, "plugins.json")
+    plugins_config = if File.exist?(plugins_file)
+                       JSON.parse(File.read(plugins_file))
+                     else
+                       { "plugins" => [] }
+                     end
+
+    plugins = plugins_config["plugins"] || []
+    if plugins.empty?
+      puts "No plugins installed."
+      puts ""
+      puts "Install plugins with: brainiac install <name>"
+      puts "  Example: brainiac install whatsapp"
+      puts "  Example: brainiac install fizzy --path ~/Code/brainiac-fizzy"
+    else
+      puts "Installed plugins:"
+      plugins.each do |p|
+        entry = p.is_a?(Hash) ? p : { "name" => p.to_s }
+        name = entry["name"]
+        gem_name = entry["gem"] || "brainiac-#{name}"
+        local_path = entry["path"]
+        installed_at = entry["installed_at"] ? " (#{entry["installed_at"][0..9]})" : ""
+
+        if local_path
+          # Local plugin — check path exists
+          if Dir.exist?(local_path)
+            puts "  ✓ #{name} → #{local_path}#{installed_at}"
+          else
+            puts "  ✗ #{name} → #{local_path} (path missing)#{installed_at}"
+          end
+        else
+          # Gem plugin — check gem is loadable
+          version = entry["version"] || "latest"
+          loadable = begin
+            spec = Gem::Specification.find_by_name(gem_name)
+            "✓ #{name} (#{gem_name} #{spec.version})"
+          rescue Gem::MissingSpecError
+            "✗ #{name} (#{gem_name} — gem not found)"
+          end
+          puts "  #{loadable}#{installed_at}"
+        end
+      end
+    end
+  else
+    puts "Usage: brainiac plugins [list]"
+    puts ""
+    puts "Managing plugins:"
+    puts "  brainiac install <name>       Install a plugin"
+    puts "  brainiac uninstall <name>     Remove a plugin"
+    puts "  brainiac plugins              List installed plugins"
+  end
+
 when "version", "--version", "-v"
   puts "brainiac #{BRAINIAC_VERSION}"
 
@@ -1956,6 +2376,9 @@ when "help", "--help", "-h", nil
       brainiac projects list          List all registered projects (alias)
       brainiac projects default <key> Set the default project
       brainiac show <key>             Show project configuration
+      brainiac install <plugin>       Install a Brainiac plugin (gem-based handler)
+      brainiac uninstall <plugin>     Remove an installed plugin
+      brainiac plugins                List installed plugins
       brainiac brain <command>        Manage agent long-term memory (brain)
       brainiac discord <command>      Manage the Discord bot
       brainiac cron <command>         Manage scheduled agent tasks
@@ -1970,6 +2393,11 @@ when "help", "--help", "-h", nil
     Server Options:
       -d, --daemon                     Run server in background (detached)
 
+    Plugin Commands:
+      install <name>                   Install a plugin (gem install brainiac-<name>)
+      uninstall <name>                 Remove a plugin
+      plugins                          List installed plugins
+
     Card Map Commands:
       card-map list                    Show all card map entries
       card-map clean                   Remove stale entries (missing worktrees)