brainiac 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c65982d3a8149b7e0378221a00612218c0d77df2fe0c82370aa7210210f125d3
-  data.tar.gz: 4fcccf1bb797b144f6382a3562e5837ada64af5d1fc3ef3abc13b8f68a3d6818
+  metadata.gz: 1e2fc609dfdad411c1262f53783c3d6d88de4dbb75c83ccb9cedf6b935555a42
+  data.tar.gz: 6c7f6aed1727d45ba3bd953554598a20222c3ed47a81879b66108fbe2e7abb98
 SHA512:
-  metadata.gz: 82764530696b3843f4723f6169e3026fb9540c5e78c833bc66cbb8642851bc70496404de3479426dc3a624197903735a4cd0b210396e06b7e81076a37467561a
-  data.tar.gz: 29e3a1a6c736f0f2cbb82908262f049aaddd5e59ded8eafb21854eae5d7f8cb83ea63c3e58df7b46bc165e0b9e681d3e4f696f09ef9a0a8994eba829b4b36497
+  metadata.gz: 68db7910a0cca76489408685a40f1fe549eaa6462ddefad4b532160b2ef8bd80c798a79b84c4daaeb538e52cc4df3412fca8f61862c39d94a49e9c080cb83e95
+  data.tar.gz: ab36e6f636e4ac76b28bfa55a418d1c00f2251adc36663e9fe21786150d3a27aa7d870bf4c225ffc47303873af38c76ed7601166be9d9ce88a2f30e372770e3b

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.9.2 — 2026-11-02
+
+- Add filesystem-search guardrail to PROMPT_CORE — forbids `find /`, `find ~`, `grep -r /`, and `locate`, which hang indefinitely on macOS (autofs, iCloud, sealed sim volumes). Teaches agents to use `gem which` / `Gem.loaded_specs` and scope `find` to known gem/repo roots with a depth limit.
+
 ## 0.9.1 — 2026-04-21
 
 - Add subagent delegation section to PROMPT_CORE — teaches agents when/how to use `use_subagent` tool, with `brainiac list` for on-demand project discovery

data/README.md

@@ -271,6 +271,15 @@ Set `agent_flag` to `null` to suppress passing the agent name entirely (for CLIs
 
 A provider without `readonly_args` can't be used read-only; the call fails instead of falling back to `default_args`.
 
+`stream_args` and `stream_format` are optional and give you a live agent log for CLIs that otherwise print nothing until they exit. `claude -p` is one: by default it prints only the final answer. `stream_args` is added only to background dispatches that write to a log (never `ask_agent`, which needs plain text). `stream_format` sends the output through a formatter that turns the JSON events into readable lines: assistant text, `▸ Bash: git status` for each tool call, and a closing `--- done · 14 turns · 6m12s · $0.82` line.
+
+```json
+"stream_args": "--output-format stream-json --verbose",
+"stream_format": "claude"
+```
+
+`claude` is the only `stream_format` so far. Lines that aren't JSON pass through unchanged.
+
 Which provider runs is decided in this order: a `[cli:X]` tag, the agent's `cli_provider` in `agents.json`, the project's `cli_provider`, then `default_cli_provider` in `brainiac.json`. With none of those set, brainiac uses the `AGENT_CLI` env var, or kiro-cli.
 
 #### Asking an agent from a plugin

data/bin/brainiac

@@ -15,7 +15,7 @@ BRAINIAC_ROOT = File.expand_path("..", __dir__)
 require_relative "../lib/brainiac/version"
 BRAINIAC_VERSION = Brainiac::VERSION
 
-BRAINIAC_DIR = File.join(Dir.home, ".brainiac")
+BRAINIAC_DIR = ENV.fetch("BRAINIAC_DIR", File.join(Dir.home, ".brainiac"))
 PROJECTS_FILE = File.join(BRAINIAC_DIR, "projects.json")
 CONFIG_FILE = File.join(BRAINIAC_DIR, "config.json")
 PID_FILE = File.join(BRAINIAC_DIR, "server.pid")
@@ -193,27 +193,135 @@ rescue StandardError
   nil
 end
 
-# Run CLI-time plugin hooks for agent lifecycle events.
-# Loads each installed plugin's CLI module and calls the hook method if defined.
-# This runs synchronously and can prompt for interactive input.
-def notify_plugins_agent_created(agent_key, entry)
+# Installed plugins whose CLI module implements on_agent_created, as
+# [name, module] pairs in plugins.json order.
+def agent_setup_plugins
   plugins_file = File.join(BRAINIAC_DIR, "plugins.json")
-  return unless File.exist?(plugins_file)
+  return [] unless File.exist?(plugins_file)
 
-  plugins_config = JSON.parse(File.read(plugins_file))
-  (plugins_config["plugins"] || []).each do |pentry|
+  (JSON.parse(File.read(plugins_file))["plugins"] || []).filter_map do |pentry|
     pname = pentry.is_a?(Hash) ? pentry["name"] : pentry.to_s
     try_require_metadata(pname, pentry)
     try_require_plugin_cli(pname, pentry)
     mod = resolve_plugin_module_for(pname)
-    next unless mod.respond_to?(:on_agent_created)
+    [pname, mod] if mod.respond_to?(:on_agent_created)
+  rescue StandardError, LoadError => e
+    puts "  ⚠ Plugin '#{pname}' couldn't load: #{e.message}"
+    nil
+  end
+rescue JSON::ParserError
+  []
+end
+
+# Run each plugin's on_agent_created hook (Discord bot, Fizzy user, ...).
+# Runs synchronously and can prompt for interactive input. Plugins in `skip`
+# are left alone; when `only` is given, just those plugins run. With
+# `confirm`, each plugin is asked about first and a "no" is added to `skip`
+# (the caller persists it so `agent setup` won't ask again).
+def notify_plugins_agent_created(agent_key, entry, skip: [], only: nil, confirm: false)
+  agent_setup_plugins.each do |pname, mod|
+    if only ? !only.include?(pname) : skip.include?(pname)
+      puts "  [#{pname}] skipped"
+      next
+    end
+
+    if confirm
+      print "\nSet up #{pname} for #{entry["display_name"] || agent_key}? [Y/n]: "
+      if $stdin.gets.to_s.strip.downcase.start_with?("n")
+        skip << pname
+        next
+      end
+    end
 
     mod.on_agent_created(agent_key, entry)
   rescue StandardError => e
     puts "  ⚠ Plugin '#{pname}' hook failed: #{e.message}"
   end
-rescue JSON::ParserError
-  nil
+end
+
+# "--skip basecamp,fizzy" style values → ["basecamp", "fizzy"]
+def plugin_list_arg(value)
+  value.to_s.split(",").map { |p| p.strip.downcase.delete_prefix("brainiac-") }.reject(&:empty?)
+end
+
+AVATAR_EXTENSIONS = %w[.png .jpg .jpeg .gif .webp].freeze
+
+# Resolve a description flag value: "-" reads stdin, "@path" reads a file,
+# anything else is the literal text.
+def read_description_arg(value)
+  return $stdin.read.strip if value == "-"
+  return File.read(File.expand_path(value[1..])).strip if value.start_with?("@")
+
+  value
+end
+
+# Open $VISUAL/$EDITOR on a scratch file so a multi-paragraph persona can be
+# written comfortably. HTML comment lines are instructions and get stripped.
+# Returns nil when the result is blank.
+def edit_description_in_editor(display_name, initial = nil)
+  require "tempfile"
+  require "shellwords"
+  editor = ENV["VISUAL"] || ENV["EDITOR"] || "vi"
+  Tempfile.create(["#{display_name.downcase}-persona", ".md"]) do |f|
+    f.write(initial || <<~MD)
+      <!-- Describe #{display_name}: personality, tone, voice, what they focus on. -->
+      <!-- Paragraphs and markdown are fine. Lines like this one are removed. Save and quit when done. -->
+
+    MD
+    f.flush
+    system(*Shellwords.split(editor), f.path)
+    text = File.read(f.path).gsub(/^\s*<!--.*?-->\s*\n?/, "").strip
+    text.empty? ? nil : text
+  end
+end
+
+# Default agent email from brainiac.json "agent_email_template",
+# e.g. "agent+{key}@example.com". Returns nil when no template is configured.
+def default_agent_email(agent_key, display_name)
+  config_path = File.join(BRAINIAC_DIR, "brainiac.json")
+  template = File.exist?(config_path) ? JSON.parse(File.read(config_path))["agent_email_template"] : nil
+  return nil if template.nil? || template.strip.empty?
+
+  template.gsub("{key}", agent_key).gsub("{name}", display_name)
+end
+
+# Copy an avatar image into the agent's persona dir (synced with the brain)
+# and return the stored path.
+def store_agent_avatar(agent_key, source)
+  path = File.expand_path(source)
+  ext = File.extname(path).downcase
+  raise ArgumentError, "Avatar not found: #{source}" unless File.file?(path)
+  raise ArgumentError, "Avatar must be one of #{AVATAR_EXTENSIONS.join(", ")}" unless AVATAR_EXTENSIONS.include?(ext)
+
+  persona_dir = File.join(BRAINIAC_DIR, "brain", "persona", agent_key)
+  FileUtils.mkdir_p(persona_dir)
+  dest = File.join(persona_dir, "avatar#{ext}")
+  FileUtils.cp(path, dest) unless File.identical?(path, dest)
+  dest
+end
+
+# The persona text for an agent, read back from its style.md (frontmatter and
+# the generated "# Name — Persona" heading removed).
+def agent_persona_description(agent_key)
+  file = File.join(BRAINIAC_DIR, "brain", "persona", agent_key, "style.md")
+  return nil unless File.exist?(file)
+
+  body = File.read(file).sub(/\A---\n.*?\n---\n/m, "").sub(/\A\s*# .*— Persona\n/, "").strip
+  body.empty? ? nil : body
+end
+
+# Payload handed to plugins' on_agent_created: the registry entry plus the
+# setup inputs plugins need to provision accounts (avatar, description, email).
+# "open_browser" tells plugins whether they may launch a browser for their
+# manual steps (false with --no-browser, BRAINIAC_NO_BROWSER, or no terminal).
+def agent_hook_payload(agent_key, entry, open_browser: true)
+  entry.merge(
+    "agent_key" => agent_key,
+    "avatar_path" => entry["avatar"],
+    "description" => agent_persona_description(agent_key),
+    "email" => entry["email"],
+    "open_browser" => open_browser && $stdin.tty? && !ENV["BRAINIAC_NO_BROWSER"]
+  ).compact
 end
 
 # Run CLI-time plugin hooks for agent removal.
@@ -561,6 +669,68 @@ def generate_plugin_skill_md(plugin_name, pascal_name)
     | `:detect_cli_provider` | Detect CLI provider |
     | `:detect_effort` | Detect effort level |
 
+    ## Agent Onboarding (`on_agent_created`)
+
+    `brainiac agent create` writes the brainiac files (agents.json, persona, brain),
+    then asks each plugin to provision the new agent on its service: a Discord bot,
+    a Fizzy user, a Basecamp person. `brainiac agent setup <name>` runs the same hook
+    again. If your plugin gives agents an identity on some service, implement it.
+
+    Define it in `cli.rb` (or a file `cli.rb` requires), since it runs in the CLI context:
+
+    ```ruby
+    # cli.rb
+    require_relative "agent_setup"
+
+    module Brainiac
+      module Plugins
+        module MyService
+          # Called by `brainiac agent create` / `brainiac agent setup`.
+          def self.on_agent_created(agent_key, entry)
+            AgentSetup.run(agent_key, entry)
+          end
+
+          def self.on_agent_removed(agent_key, display_name) # optional: clean up config
+          end
+        end
+      end
+    end
+    ```
+
+    `entry` is the agents.json entry plus:
+
+    | Key | Value |
+    |-----|-------|
+    | `agent_key` | Registry key, e.g. `quill` |
+    | `display_name` | e.g. `Quill` |
+    | `avatar_path` | Profile image (png/jpg/gif/webp) or absent |
+    | `description` | Persona text (can be several paragraphs) or absent |
+    | `email` | Email for the agent's accounts (from `--email` / `agent_email_template`) or absent |
+    | `open_browser` | `true` when you may launch a browser for a manual step |
+
+    Rules:
+
+    1. **Idempotent.** `agent setup` re-runs every hook. Check your config first and
+       print `✓ <Name> already ... (skipping)` when the work is done.
+    2. **Automate everything the API allows.** Only stop for steps the service truly
+       can't do by API (e.g. Discord has no create-application endpoint). Then print
+       numbered steps and the URL, and read the result with `$stdin.noecho(&:gets)`
+       for secrets.
+    3. **Browser.** If `entry["open_browser"]` is true, open the URL as well as printing
+       it (`xdg-open` on Linux, `open` on macOS, spawned and detached). Don't open links
+       that must be used while signed in as someone else (e.g. a join link for the bot's
+       own account), because they'd land in the user's own session. Say "open in a
+       private window" instead.
+    4. **Optional inputs.** Skip quietly if `avatar_path`, `description` or `email` is missing.
+       Return without error when `$stdin` isn't a TTY and you need input.
+    5. **Never raise for expected failures.** Print `✗ ... re-run: brainiac agent setup <key>`.
+       Uncaught exceptions are reported as "hook failed" and the next plugin runs.
+    6. **Prefix output** with `  [MyService]` so it's clear whose step is running.
+
+    Users choose which plugins run with `--skip` / `--only` (or by answering "n" when
+    asked during create). Core filters on the plugin name before calling you, so
+    plugins don't need to handle this.
+
     ## Channel Prompts
 
     For communication channel plugins:
@@ -2254,18 +2424,28 @@ when "agent"
       puts "Usage: brainiac agent create <name> [options]"
       puts ""
       puts "Options:"
-      puts "  --local              Mark agent as local (dispatches on this machine)"
-      puts "  --role <role>        Assign a role (repeatable)"
-      puts "  --cli <provider>     Set CLI provider (default: kiro)"
-      puts "  --persona <text>     Create a persona style file with this description"
+      puts "  --avatar <path>        Profile picture (png/jpg/gif/webp), used by plugins (Discord, Fizzy)"
+      puts "  --description <text>   Persona description (\"-\" reads stdin, \"@file\" reads a file)"
+      puts "  --description-file <path>  Read the persona description from a file"
+      puts "  --email <address>      Email for the agent's accounts (default: agent_email_template)"
+      puts "  --local                Mark agent as local (dispatches on this machine)"
+      puts "  --role <role>          Assign a role (repeatable)"
+      puts "  --cli <provider>       Set CLI provider (default: kiro)"
+      puts "  --skip <plugins>       Don't set up these plugins for this agent, e.g. --skip basecamp"
+      puts "  --only <plugins>       Set up just these plugins, e.g. --only discord,fizzy"
+      puts "  --no-browser           Print setup links instead of opening them"
       puts ""
-      puts "If no options are given and stdin is a terminal, interactive mode is used."
+      puts "With no flags and a terminal, interactive mode is used. If no description is"
+      puts "given on a terminal, $EDITOR opens so you can write a full persona."
+      puts "After the brainiac files are written, each installed plugin sets up its part"
+      puts "(Discord bot, Fizzy user, Basecamp person), asking first unless --skip/--only"
+      puts "is given. Re-run with: brainiac agent setup <name>"
       puts ""
       puts "Examples:"
-      puts "  brainiac agent create MyAgent   # interactive"
+      puts "  brainiac agent create Quill --local --avatar quill.png   # opens $EDITOR for the persona"
+      puts "  brainiac agent create Quill --local --avatar quill.png --description @quill.md"
+      puts "  brainiac agent create MyAgent                            # interactive"
       puts "  brainiac agent create SecurityBot --local --role code-reviewer"
-      puts "  brainiac agent create Jane --role general-engineer --cli grok"
-      puts "  brainiac agent create Merlin --persona \"Wise, enigmatic, helpful\""
       exit 1
     end
 
@@ -2273,7 +2453,8 @@ when "agent"
     registry = File.exist?(agent_registry_file) ? JSON.parse(File.read(agent_registry_file)) : {}
 
     if registry[agent_key]
-      puts "Agent '#{name}' already exists. Use 'brainiac agent #{agent_key} show' to view."
+      puts "Agent '#{name}' already exists. Use 'brainiac agent #{agent_key} show' to view,"
+      puts "or 'brainiac agent setup #{agent_key}' to finish plugin setup."
       exit 1
     end
 
@@ -2281,6 +2462,11 @@ when "agent"
     roles = []
     cli_provider = nil
     persona_text = nil
+    avatar = nil
+    email = nil
+    skip_plugins = []
+    only_plugins = nil
+    open_browser = true
 
     if ARGV.any?
       # Flag mode
@@ -2295,9 +2481,27 @@ when "agent"
         when "--cli"
           ARGV.shift
           cli_provider = ARGV.shift
-        when "--persona"
+        when "--description", "--persona"
+          ARGV.shift
+          persona_text = read_description_arg(ARGV.shift.to_s)
+        when "--description-file"
+          ARGV.shift
+          persona_text = File.read(File.expand_path(ARGV.shift.to_s)).strip
+        when "--avatar"
           ARGV.shift
-          persona_text = ARGV.shift
+          avatar = ARGV.shift
+        when "--email"
+          ARGV.shift
+          email = ARGV.shift
+        when "--skip"
+          ARGV.shift
+          skip_plugins.concat(plugin_list_arg(ARGV.shift))
+        when "--only"
+          ARGV.shift
+          only_plugins = plugin_list_arg(ARGV.shift)
+        when "--no-browser"
+          ARGV.shift
+          open_browser = false
         else
           puts "Unknown option: #{ARGV[0]}"
           exit 1
@@ -2327,15 +2531,39 @@ when "agent"
       input = $stdin.gets.chomp
       roles = input.empty? ? [] : input.split(",").map(&:strip)
 
-      print "Persona description (tone/style, or blank to skip) []: "
+      print "Avatar image path (or blank to skip) []: "
+      input = $stdin.gets.chomp
+      avatar = input.empty? ? nil : input
+
+      default_email = default_agent_email(agent_key, name)
+      print "Email for the agent's accounts#{" [#{default_email}]" if default_email}: "
       input = $stdin.gets.chomp
-      persona_text = input.empty? ? nil : input
+      email = input.empty? ? default_email : input
     end
 
+    # A persona is usually a paragraph or more — give it a real editor.
+    if persona_text.nil? && $stdin.tty?
+      print "Write #{name}'s persona description in #{ENV["VISUAL"] || ENV["EDITOR"] || "vi"}? [Y/n]: "
+      persona_text = edit_description_in_editor(name) unless $stdin.gets.to_s.strip.downcase.start_with?("n")
+    end
+
+    email ||= default_agent_email(agent_key, 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?
+    entry["email"] = email if email
+    entry["skip_plugins"] = skip_plugins.uniq if skip_plugins.any?
+
+    if avatar
+      begin
+        entry["avatar"] = store_agent_avatar(agent_key, avatar)
+      rescue ArgumentError => e
+        puts "❌ #{e.message}"
+        exit 1
+      end
+    end
 
     registry[agent_key] = entry
     File.write(agent_registry_file, JSON.pretty_generate(registry))
@@ -2343,6 +2571,8 @@ when "agent"
     puts "  Local: #{local}" if local
     puts "  Role: #{roles.join(", ")}" if roles.any?
     puts "  CLI: #{cli_provider}" if cli_provider
+    puts "  Email: #{email}" if email
+    puts "  Avatar: #{entry["avatar"]}" if entry["avatar"]
 
     # Create persona directory and style file if requested
     if persona_text
@@ -2356,6 +2586,7 @@ when "agent"
           description: Persona voice for #{name}.
           ---
           # #{name} — Persona
+
           #{persona_text}
         MD
         puts "  Persona: #{persona_file}"
@@ -2368,12 +2599,82 @@ when "agent"
       brain_init(name)
     end
 
-    # Let plugins prompt for additional config (e.g. Discord user ID)
-    notify_plugins_agent_created(agent_key, entry)
+    # Each plugin provisions its side (Discord bot, Fizzy user, Basecamp person, ...).
+    # Without --skip/--only, a terminal user is asked per plugin; "no" answers
+    # are saved so `agent setup` leaves those plugins alone too.
+    confirm = $stdin.tty? && skip_plugins.empty? && only_plugins.nil?
+    notify_plugins_agent_created(agent_key, agent_hook_payload(agent_key, entry, open_browser: open_browser),
+                                 skip: skip_plugins, only: only_plugins, confirm: confirm)
+    if skip_plugins.any? && entry["skip_plugins"] != skip_plugins.uniq
+      entry["skip_plugins"] = skip_plugins.uniq
+      registry[agent_key] = entry
+      File.write(agent_registry_file, JSON.pretty_generate(registry))
+      puts "  Skipping #{skip_plugins.uniq.join(", ")} for #{name} (undo: brainiac agent setup #{agent_key} --only <plugin>)"
+    end
 
     # Notify running server to reload and trigger :agent_added hook
     notify_server_reload
 
+  when "setup"
+    name = ARGV.shift
+    unless name
+      puts "Usage: brainiac agent setup <name> [--avatar <path>] [--email <address>] [--skip <plugins>] [--only <plugins>] [--no-browser]"
+      puts ""
+      puts "Re-runs every plugin's agent setup (Discord bot, Fizzy user, Basecamp person)."
+      puts "Steps that are already done are skipped, so it's safe to run after an"
+      puts "interrupted 'agent create' or to set up a newly installed plugin."
+      puts ""
+      puts "  --skip a,b    Never set up these plugins for this agent (saved)"
+      puts "  --only a,b    Run just these plugins (also un-skips them)"
+      puts "  --no-browser  Print links instead of opening them"
+      exit 1
+    end
+
+    agent_key = name.downcase.gsub(/[^a-z0-9-]/, "-")
+    registry = File.exist?(agent_registry_file) ? JSON.parse(File.read(agent_registry_file)) : {}
+    entry = registry[agent_key]
+    unless entry
+      puts "Agent '#{name}' not found in registry."
+      exit 1
+    end
+
+    only_plugins = nil
+    open_browser = true
+    while ARGV.any?
+      case ARGV.shift
+      when "--skip"
+        entry["skip_plugins"] = ((entry["skip_plugins"] || []) + plugin_list_arg(ARGV.shift)).uniq
+      when "--only"
+        only_plugins = plugin_list_arg(ARGV.shift)
+      when "--no-browser"
+        open_browser = false
+      when "--avatar"
+        begin
+          entry["avatar"] = store_agent_avatar(agent_key, ARGV.shift.to_s)
+        rescue ArgumentError => e
+          puts "❌ #{e.message}"
+          exit 1
+        end
+      when "--email"
+        entry["email"] = ARGV.shift
+      else
+        puts "Unknown option. Run 'brainiac agent setup' for usage."
+        exit 1
+      end
+    end
+    entry["email"] ||= default_agent_email(agent_key, entry["display_name"] || name)
+    entry.delete("email") unless entry["email"]
+    # Explicitly running a plugin with --only un-skips it for good.
+    entry["skip_plugins"] -= only_plugins if only_plugins && entry["skip_plugins"]
+    entry.delete("skip_plugins") if entry["skip_plugins"] == []
+    registry[agent_key] = entry
+    File.write(agent_registry_file, JSON.pretty_generate(registry))
+
+    puts "Setting up #{entry["display_name"] || name} (#{agent_key})"
+    notify_plugins_agent_created(agent_key, agent_hook_payload(agent_key, entry, open_browser: open_browser),
+                                 skip: entry["skip_plugins"] || [], only: only_plugins)
+    notify_server_reload
+
   when "remove", "delete", "rm"
     name = ARGV.shift
     unless name
@@ -2407,12 +2708,14 @@ when "agent"
              brainiac agent list
              brainiac agent default [name]
              brainiac agent create <name> [options]
+             brainiac agent setup <name> [--skip|--only <plugins>]
              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
+        create <name> [options]           Add a new agent and run every plugin's setup
+        setup <name>                      Re-run plugin setup (skips steps already done)
         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, display_name)
@@ -2421,14 +2724,21 @@ when "agent"
         <name> env --delete <KEY>         Remove an env var from an agent
 
       Create options (or interactive if no flags given):
+        --avatar <path>      Profile picture, used by plugins (Discord, Fizzy)
+        --description <text> Persona description ("-" = stdin, "@file" = file; $EDITOR if omitted)
+        --email <address>    Email for the agent's accounts (default: agent_email_template)
         --local              Mark agent as local (dispatches on this machine)
         --role <role>        Assign a role (repeatable)
         --cli <provider>     Set CLI provider (default: kiro)
-        --persona <text>     Create a persona style file
+        --skip <plugins>     Don't set up these plugins for this agent (saved; also for setup)
+        --only <plugins>     Set up just these plugins (also for setup)
+        --no-browser         Print setup links instead of opening them
 
       Examples:
         brainiac agent list
         brainiac agent default Sherlock
+        brainiac agent create Quill --local --avatar quill.png
+        brainiac agent setup quill
         brainiac agent create SecurityBot --local --role code-reviewer
         brainiac agent create Jane --cli grok
         brainiac agent create MyAgent             # interactive mode
@@ -3249,6 +3559,12 @@ when "plugin"
               Cli.run(args)
             end
 
+            # Optional: provision a new agent on #{pascal_name} during
+            # `brainiac agent create` / `brainiac agent setup`. Must be idempotent.
+            # See "Agent Onboarding" in skills/#{plugin_name}/SKILL.md for the payload and rules.
+            # def self.on_agent_created(agent_key, entry)
+            # end
+
             # Subcommand names for bash completion.
             def self.completions
               %w[config setup status]

data/bin/brainiac-completion.bash

@@ -109,14 +109,14 @@ _brainiac() {
     agent)
       case $cword in
         2)
-          COMPREPLY=($(compgen -W "list create remove $(_brainiac_agents)" -- "$cur"))
+          COMPREPLY=($(compgen -W "list create setup remove $(_brainiac_agents)" -- "$cur"))
           ;;
         3)
           local agent_name="${words[2]}"
           case "$agent_name" in
-            list|remove|delete|rm) ;;
+            list|remove|delete|rm|setup) ;;
             create|add)
-              COMPREPLY=($(compgen -W "--local --role --cli --persona" -- "$cur"))
+              COMPREPLY=($(compgen -W "--avatar --description --description-file --email --local --role --cli --skip --only --no-browser" -- "$cur"))
               ;;
             *)
               COMPREPLY=($(compgen -W "show env" -- "$cur"))

data/lib/brainiac/helpers.rb

@@ -35,7 +35,7 @@ def load_cli_provider(provider_name)
   %w[prompt_flag readonly_args list_models_command resume_flag resume_args resume_id_flag new_session_id_flag
      session_list_command session_id_field session_directory_field session_updated_field
      session_list_path session_dir output_last_message_flag cwd_flag config_override_flag
-     effort_config_key effort_map title_flag heaviness_probe settings_model_cmd].each do |key|
+     effort_config_key effort_map title_flag heaviness_probe settings_model_cmd stream_args stream_format].each do |key|
     next unless raw[key]
     next if raw[key].respond_to?(:empty?) && raw[key].empty?
 
@@ -942,6 +942,7 @@ def run_agent(prompt, project_config:, chdir: nil, log_name: "agent", model: nil
                                   prompt_file: prompt_file, resume: should_resume,
                                   output_file: output_file, chdir: chdir, title: work_item_id,
                                   new_session_id: minted_session_id)
+  append_stream_args(cmd, resolved)
   # Profile env (named bundle, e.g. an alternate kiro-cli account) layers between
   # agent env and the explicit `env:` passed in. An explicitly-requested profile
   # wins over agent env; the default profile is only a fallback. See profiles.rb.
@@ -962,10 +963,11 @@ def run_agent(prompt, project_config:, chdir: nil, log_name: "agent", model: nil
 
   started_at = Time.now
   stdin_redirect = (resolved["prompt_mode"] || "stdin") == "stdin" ? { in: prompt_file } : {}
-  pid = spawn(spawn_env, *cmd, chdir: chdir, **stdin_redirect, out: [log_file, "w"], err: %i[child out])
+  pid, formatter = spawn_agent_process(spawn_env, cmd, resolved,
+                                       chdir: chdir, log_file: log_file, stdin_redirect: stdin_redirect)
 
   spawn_completion_watcher(
-    pid: pid, agent_cli: resolved["agent_cli"], agent_config_name: agent_config_name,
+    pid: pid, formatter: formatter, agent_cli: resolved["agent_cli"], agent_config_name: agent_config_name,
     agent_name: agent_name, log_file: log_file, log_name: log_name,
     prompt_file: prompt_file, chdir: chdir, source: source,
     source_context: source_context, project_config: project_config,
@@ -982,10 +984,42 @@ def run_agent(prompt, project_config:, chdir: nil, log_name: "agent", model: nil
   [pid, log_file]
 end
 
+# stream_args (e.g. claude's --output-format stream-json) only apply to run_agent, where
+# output goes to a log. ask_agent shares build_agent_cmd and needs plain text on stdout.
+def append_stream_args(cmd, resolved)
+  cmd.concat(resolved["stream_args"].split) if resolved["stream_args"]
+end
+
+STREAM_FORMATTER_PATH = File.expand_path("stream_formatter.rb", __dir__)
+# How long to wait for the formatter to drain after the agent exits. It normally sees EOF
+# right away, but a background process the agent left running can hold the pipe open.
+STREAM_FORMATTER_DRAIN_SECONDS = 10
+
+# Start the agent with its output going to log_file. When the provider sets stream_format,
+# the agent writes to a pipe instead and a separate formatter process turns the JSONL into
+# readable lines in the log. Both are plain child processes, so they outlive a server restart
+# the same way the agent alone does. Returns [agent_pid, formatter_waiter_or_nil].
+def spawn_agent_process(spawn_env, cmd, resolved, chdir:, log_file:, stdin_redirect:)
+  return [spawn(spawn_env, *cmd, chdir: chdir, **stdin_redirect, out: [log_file, "w"], err: %i[child out]), nil] unless resolved["stream_format"]
+
+  reader, writer = IO.pipe
+  formatter_pid = spawn(RbConfig.ruby, STREAM_FORMATTER_PATH, resolved["stream_format"],
+                        in: reader, out: [log_file, "w"], err: %i[child out])
+  pid = spawn(spawn_env, *cmd, chdir: chdir, **stdin_redirect, out: writer, err: writer)
+  [pid, Process.detach(formatter_pid)]
+ensure
+  reader&.close
+  writer&.close
+end
+
 # Spawn a background thread that waits for the agent process to finish and runs completion handling.
 def spawn_completion_watcher(**ctx)
+  formatter = ctx.delete(:formatter)
   thread = Thread.new do
     Process.wait(ctx[:pid])
+    # Let the formatter finish writing the log before completion reads it. It runs in its
+    # own waiter thread, so $CHILD_STATUS here still belongs to the agent.
+    formatter&.join(STREAM_FORMATTER_DRAIN_SECONDS)
     handle_agent_completion(**ctx)
   end
   # Without this, an unrescued exception anywhere in handle_agent_completion silently

data/lib/brainiac/prompts.rb

@@ -58,6 +58,18 @@ PROMPT_CORE = <<~PROMPT
   Standard unix commands (cd, ls, grep, cat, git, curl, etc.) don't need a brain search.
   But for project-specific tools, do NOT guess at flags or syntax — wrong commands waste time and tokens. Look it up first.
 
+  **NEVER run a whole-filesystem search.** Do not run `find /`, `find ~`, `grep -r /`, `locate`, or any
+  command that walks the entire disk from root or home. On macOS these effectively never return — they
+  block on autofs automounts, iCloud Drive cloud-only files, sealed CoreSimulator volumes, and Spotlight
+  stores — and they pin a CPU for hours. To locate an installed gem or plugin, scope the search:
+  ```
+  gem which <gem-name>                                   # exact file for a loaded gem
+  ruby -e 'puts Gem.loaded_specs.keys.grep(/<pattern>/)' # list matching loaded gems
+  # Only if those fail, scope find to known roots with a timeout and head:
+  find "$(gem env gemdir)" ~/.asdf/installs ./ -maxdepth 6 -path '*<pattern>*' -name '*.rb' 2>/dev/null | head
+  ```
+  Always point `find`/`grep -r` at a specific repo, gem root, or directory — never at `/` or `~`.
+
   **When to save knowledge:** Be selective — only save significant architecture decisions,
   non-obvious gotchas, major workflow changes, or things the user explicitly asks you to remember.
   Routine card work and things already documented in the codebase don't need brain entries.

data/lib/brainiac/stream_formatter.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# Turns a CLI's JSONL event stream into a readable agent log.
+#
+# run_agent spawns this as its own process between the agent and the log file when the
+# provider sets `stream_format` (see run_agent / spawn_agent_with_formatter). It runs
+# outside the server so a brainiac restart can't break the pipe and kill the agent.
+#
+#   claude ... --output-format stream-json --verbose | ruby stream_formatter.rb claude > log
+#
+# Lines that aren't JSON (mise noise, stderr, crashes) pass through unchanged, so the
+# crash snippet still shows whatever went wrong. Summary lines start with "---" so
+# detect_no_output_reason treats them as boilerplate, like it does kiro's banners.
+
+require "json"
+
+module StreamFormatter
+  MAX_SUMMARY = 160
+
+  module_function
+
+  # Format a single line of stream output. Returns an array of log lines (maybe empty).
+  def format_line(format, line)
+    event = JSON.parse(line)
+    return [line.chomp] unless event.is_a?(Hash)
+
+    case format
+    when "claude" then format_claude(event)
+    else [line.chomp]
+    end
+  rescue JSON::ParserError
+    [line.chomp]
+  end
+
+  def format_claude(event)
+    case event["type"]
+    when "system" then claude_system(event)
+    when "assistant" then claude_assistant(event)
+    when "user" then claude_tool_errors(event)
+    when "result" then claude_result(event)
+    else []
+    end
+  end
+
+  def claude_system(event)
+    return [] unless event["subtype"] == "init"
+
+    ["--- claude #{event["claude_code_version"]} · #{event["model"]} · session #{event["session_id"]}"]
+  end
+
+  # Assistant text prints as-is; each tool call becomes a "▸ Tool: summary" line.
+  # Events from a subagent carry parent_tool_use_id and are indented under it.
+  def claude_assistant(event)
+    indent = event["parent_tool_use_id"] ? "  " : ""
+    Array(event.dig("message", "content")).flat_map do |block|
+      case block["type"]
+      when "text"
+        text = block["text"].to_s.strip
+        text.empty? ? [] : text.lines.map { |l| "#{indent}#{l.chomp}" } + [""]
+      when "tool_use"
+        summary = tool_summary(block["name"], block["input"] || {})
+        ["#{indent}▸ #{block["name"]}#{": #{summary}" unless summary.empty?}"]
+      else []
+      end
+    end
+  end
+
+  # Successful tool results are noise in a progress log; failed ones are worth a line.
+  def claude_tool_errors(event)
+    indent = event["parent_tool_use_id"] ? "    " : "  "
+    Array(event.dig("message", "content")).filter_map do |block|
+      next unless block.is_a?(Hash) && block["type"] == "tool_result" && block["is_error"]
+
+      "#{indent}✗ #{truncate(first_line(result_text(block["content"])))}"
+    end
+  end
+
+  def claude_result(event)
+    parts = [event["subtype"] == "success" ? "done" : event["subtype"]]
+    parts << "#{event["num_turns"]} turns" if event["num_turns"]
+    parts << format_duration(event["duration_ms"]) if event["duration_ms"]
+    parts << format("$%.2f", event["total_cost_usd"]) if event["total_cost_usd"]
+    lines = ["--- #{parts.join(" · ")}"]
+    # Errors (usage limits, API failures) only show up here, so print the message where
+    # detect_no_output_reason can match it.
+    lines.unshift("✗ #{event["result"]}") if event["is_error"] && event["result"]
+    lines
+  end
+
+  def tool_summary(name, input)
+    value = case name
+            when "Bash" then input["command"]
+            when "Read", "Edit", "Write", "MultiEdit" then input["file_path"]
+            when "NotebookEdit" then input["notebook_path"]
+            when "Grep", "Glob" then [input["pattern"], input["path"]].compact.join(" in ")
+            when "Agent", "Task" then input["description"]
+            when "WebFetch" then input["url"]
+            when "WebSearch" then input["query"]
+            when "Skill" then input["skill"]
+            else input.values.find { |v| v.is_a?(String) }
+            end
+    truncate(first_line(value.to_s))
+  end
+
+  def result_text(content)
+    return content.to_s unless content.is_a?(Array)
+
+    content.filter_map { |c| c["text"] if c.is_a?(Hash) }.join("\n")
+  end
+
+  def first_line(text)
+    text.strip.lines.first.to_s.chomp
+  end
+
+  def truncate(text)
+    text.length > MAX_SUMMARY ? "#{text[0, MAX_SUMMARY - 1]}…" : text
+  end
+
+  def format_duration(millis)
+    secs = (millis / 1000.0).round
+    secs < 60 ? "#{secs}s" : "#{secs / 60}m#{format("%02d", secs % 60)}s"
+  end
+
+  def run(format, input: $stdin, output: $stdout)
+    output.sync = true
+    input.each_line do |line|
+      format_line(format, line).each { |l| output.puts(l) }
+    end
+  end
+end
+
+StreamFormatter.run(ARGV.fetch(0, "claude")) if $PROGRAM_NAME == __FILE__

data/lib/brainiac/version.rb

@@ -2,5 +2,5 @@
 
 module Brainiac
   # @return [String] the current gem version
-  VERSION = "0.2.1"
+  VERSION = "0.4.0"
 end

data/skills/brainiac-plugins/SKILL.md

@@ -110,6 +110,68 @@ Available hooks:
 | `:detect_cli_provider` | Detect CLI provider | metadata hash |
 | `:detect_effort` | Detect effort level | metadata hash |
 
+## Agent Onboarding (`on_agent_created`)
+
+`brainiac agent create` writes the brainiac files (agents.json, persona, brain),
+then asks each plugin to provision the new agent on its service: a Discord bot,
+a Fizzy user, a Basecamp person. `brainiac agent setup <name>` runs the same hook
+again. If your plugin gives agents an identity on some service, implement it.
+
+Define it in `cli.rb` (or a file `cli.rb` requires), since it runs in the CLI context:
+
+```ruby
+# cli.rb
+require_relative "agent_setup"
+
+module Brainiac
+  module Plugins
+    module MyService
+      # Called by `brainiac agent create` / `brainiac agent setup`.
+      def self.on_agent_created(agent_key, entry)
+        AgentSetup.run(agent_key, entry)
+      end
+
+      def self.on_agent_removed(agent_key, display_name) # optional: clean up config
+      end
+    end
+  end
+end
+```
+
+`entry` is the agents.json entry plus:
+
+| Key | Value |
+|-----|-------|
+| `agent_key` | Registry key, e.g. `quill` |
+| `display_name` | e.g. `Quill` |
+| `avatar_path` | Profile image (png/jpg/gif/webp) or absent |
+| `description` | Persona text (can be several paragraphs) or absent |
+| `email` | Email for the agent's accounts (from `--email` / `agent_email_template`) or absent |
+| `open_browser` | `true` when you may launch a browser for a manual step |
+
+Rules:
+
+1. **Idempotent.** `agent setup` re-runs every hook. Check your config first and
+   print `✓ <Name> already ... (skipping)` when the work is done.
+2. **Automate everything the API allows.** Only stop for steps the service truly
+   can't do by API (e.g. Discord has no create-application endpoint). Then print
+   numbered steps and the URL, and read the result with `$stdin.noecho(&:gets)`
+   for secrets.
+3. **Browser.** If `entry["open_browser"]` is true, open the URL as well as printing
+   it (`xdg-open` on Linux, `open` on macOS, spawned and detached). Don't open links
+   that must be used while signed in as someone else (e.g. a join link for the bot's
+   own account), because they'd land in the user's own session. Say "open in a
+   private window" instead.
+4. **Optional inputs.** Skip quietly if `avatar_path`, `description` or `email` is missing.
+   Return without error when `$stdin` isn't a TTY and you need input.
+5. **Never raise for expected failures.** Print `✗ ... re-run: brainiac agent setup <key>`.
+   Uncaught exceptions are reported as "hook failed" and the next plugin runs.
+6. **Prefix output** with `  [MyService]` so it's clear whose step is running.
+
+Users choose which plugins run with `--skip` / `--only` (or by answering "n" when
+asked during create). Core filters on the plugin name before calling you, so
+plugins don't need to handle this.
+
 ## Channel Prompts
 
 If your plugin is a communication channel (like Discord, Fizzy), register a prompt:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainiac
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Andy Davis
@@ -146,6 +146,7 @@ files:
 - lib/brainiac/session_history.rb
 - lib/brainiac/sessions.rb
 - lib/brainiac/skills.rb
+- lib/brainiac/stream_formatter.rb
 - lib/brainiac/users.rb
 - lib/brainiac/version.rb
 - monitor/daemon.rb