tinker-agent 1.0.56 → 1.0.59

package/agents.rb

@@ -91,6 +91,29 @@ If blocked (e.g., missing tools, auth errors, ambiguous requirements):
 3.  **Priority:** High or Critical.
 4.  **Context:** Include action attempted, error details, related Ticket ID, and suggested fix.
 
+### BUG HANDLING PRIORITY (CRITICAL)
+
+When you discover a bug during implementation:
+
+**MANDATORY WORKFLOW:**
+1. **FIX IT NOW** - Write code to resolve the issue immediately
+2. **TEST IT** - Add tests to prevent regression and verify the fix
+3. **ESCALATE ONLY** - If you absolutely cannot fix it, create a ticket explaining WHY
+
+**FORBIDDEN (ANTI-PATTERNS):**
+*   ❌ Writing PR comments or tests that describe bugs without fixing them
+*   ❌ Creating documentation for unfixed bugs
+*   ❌ Adding TODO comments for bugs you could fix yourself
+*   ❌ Marking tests as "KNOWN BUG" or "xfail" to document issues
+
+**WHY THIS MATTERS:**
+*   **User Trust:** "Documenting bugs" looks like laziness or incompetence
+*   **Code Quality:** Production code should not have known bugs
+*   **Team Value:** Agentic team should reduce bug count, not catalog it
+*   **Reference:** Knowledge Article #36 defines this standard
+
+**USER TRUST DEPENDS ON FIXING BUGS, NOT CATALOGING THEM.**
+
 ### UNIVERSAL TECHNICAL CONSTRAINTS
 1.  **Tool Formatting:** Do NOT use a colon before tool calls (e.g., write "Let me search" NOT "Let me search:").
 2.  **URL Safety:** NEVER guess or hallucinate URLs. Use only known valid URLs.
@@ -122,10 +145,15 @@ You are the **TINKER REVIEWER** agent operating in **FULLY AUTONOMOUS MODE**.
 2.  **MANDATORY:** Run test suite (`bundle exec rspec`) **BEFORE** any approval decision.
 3.  **Detect missing specs:** Ensure file changes have corresponding tests.
 4.  **Reject (Fail):** If tests fail or specs are missing, you MUST reject.
-5.  **Feedback:** Add `code_review` comments with findings.
-6.  **Transition:** Use `pass_audit` or `fail_audit`.
-7.  **Knowledge:** Search memory for project standards.
-8.  **Completion:** Mark idle after completing the review.
+5.  **CRITICAL:** Reject PRs that document bugs without fixing them.
+    *   Watch for: Tests marked "KNOWN BUG", "xfail", or similar that intentionally fail
+    *   Watch for: PR comments describing unfixed issues instead of fixing them
+    *   Watch for: TODO comments for bugs the worker could have fixed
+    *   **Standard:** Workers MUST FIX bugs they discover, not catalog them (KB #36)
+6.  **Feedback:** Add `code_review` comments with findings.
+7.  **Transition:** Use `pass_audit` or `fail_audit`.
+8.  **Knowledge:** Search memory for project standards.
+9.  **Completion:** Mark idle after completing the review.
 
 ### FORBIDDEN ACTIONS (STRICT)
 *   Do NOT implement new features or functionality.
@@ -198,7 +226,7 @@ You must use `create_proposal` to suggest actions.
 2. **Analysis & Memory**
    - Analyze patterns across tickets and code.
    - Store observations using `store_memory`.
-   - Identify stale or incorrect memories and create `memory_cleanup` proposals.
+   - Identify stale or incorrect memories and delete them using `delete_memory` tool (autonomous cleanup).
 
 3. **Knowledge Base Maintenance**
    - **Consult First:** Always search for human instructions (`tags: instruction`) and architectural patterns before proposing changes.
@@ -218,7 +246,7 @@ You must use `create_proposal` to suggest actions.
 **Structure:**
 Every proposal must include:
 - `title`: Clear and concise.
-- `proposal_type`: One of [new_ticket, memory_cleanup, refactor, test_gap, feature].
+- `proposal_type`: One of [new_ticket, refactor, test_gap, feature].
 - `reasoning`: Why this matters.
 - `confidence`: high/medium/low.
 - `priority`: high/medium/low.
@@ -226,7 +254,6 @@ Every proposal must include:
 
 **Types:**
 - `new_ticket`: Suggest a new task to be created.
-- `memory_cleanup`: Request deletion of stale/incorrect memories.
 - `refactor`: Identify code requiring refactoring.
 - `test_gap`: Find missing test coverage.
 - `feature`: Suggest new features or improvements.
@@ -237,7 +264,6 @@ Every proposal must include:
 
 **ABSOLUTELY FORBIDDEN:**
 - Modifying code, tickets, or files directly.
-- Deleting or modifying memories directly (use `memory_cleanup` proposal).
 - Writing, editing, or refactoring code.
 - Making git commits or pull requests.
 - Sending messages to other agents.

package/bin/install-agent.sh

@@ -7,7 +7,7 @@ export DEBIAN_FRONTEND=noninteractive
 echo 'Acquire::Check-Date "false";' > /etc/apt/apt.conf.d/99no-check-date
 
 apt-get update && apt-get install -y \
-    git curl tmux sudo unzip wget
+    git curl tmux sudo unzip wget jq nano
 
 # Install Node.js (required for Claude CLI)
 # Check for existing Node installation

package/{run-tinker-agent.rb → bin/run-tinker-agent.rb}

@@ -11,10 +11,10 @@
 #   - Dockerfile.sandbox in project root
 #   - tinker.env.rb in project root (gitignored)
 
-require_relative "lib/tinker_agent/config"
-require_relative "lib/tinker_agent/docker"
-require_relative "lib/tinker_agent/agent"
-require_relative "agents"
+require_relative "../lib/tinker_agent/config"
+require_relative "../lib/tinker_agent/docker"
+require_relative "../lib/tinker_agent/agent"
+require_relative "../agents"
 
 def show_usage
   puts "Tinker Agent Runner"
@@ -39,9 +39,12 @@ if command == "attach"
   agent_type = ARGV[1]&.downcase
   abort "Usage: npx tinker-agent attach [agent-type]" unless agent_type
   config = TinkerAgent::Config.load
+  TinkerAgent::Config.fetch_repositories!(config)
   TinkerAgent::Agent.attach(agent_type, config, AGENT_CONFIGS)
 else
   config = TinkerAgent::Config.load
+  # Fetch repositories from Rails API before building
+  TinkerAgent::Config.fetch_repositories!(config)
   TinkerAgent::Docker.build_image(config)
   TinkerAgent::Agent.run(command, config, AGENT_CONFIGS)
 end

package/lib/tinker_agent/agent.rb

@@ -22,7 +22,26 @@ module TinkerAgent
       # Write banner to a persistent temp file (not auto-deleted)
       banner_path = "/tmp/tinker-agent-banner-#{agent_type}.txt"
       FileUtils.rm_rf(banner_path)
-      File.write(banner_path, agent_def[:banner])
+
+      # Append repository context to banner
+      banner_content = agent_def[:banner].dup
+      if config["repositories"]&.any?
+        sorted_repos = config["repositories"].sort_by { |r| r["position"] || 0 }
+        repo_info = sorted_repos.map do |repo|
+          name = repo["name"]
+          path = repo["path_in_sandbox"] || "/workspace/#{name}"
+          "  - **#{name}**: #{path}"
+        end.join("\n")
+
+        banner_content += "\n\n## REPOSITORY STRUCTURE\n\n"
+        banner_content += "This project has #{sorted_repos.count} repositories:\n\n"
+        banner_content += "#{repo_info}\n\n"
+        banner_content += "### Repository Switching\n\n"
+        banner_content += "Use `switch-to-repo.sh <name>` to change working directories:\n\n"
+        banner_content += "```bash\nswitch-to-repo.sh tinker\nswitch-to-repo.sh tinker-public\n```\n"
+      end
+
+      File.write(banner_path, banner_content)
 
       docker_cmd = build_docker_command(container_name, agent_type, config, agent_config, agent_def, banner_path)
 
@@ -134,6 +153,7 @@ module TinkerAgent
 
       add_github_auth!(docker_cmd, config)
       add_git_config!(docker_cmd, config)
+      add_repository_mounts!(docker_cmd, config)
       add_development_mounts!(docker_cmd)
 
       local_setup_script = File.join(File.dirname(__FILE__), "..", "..", "setup-agent.rb")
@@ -182,26 +202,67 @@ module TinkerAgent
       docker_cmd.concat(["-e", "GIT_USER_EMAIL=#{git_config['user_email']}"]) if git_config["user_email"]
     end
 
+    def self.add_repository_mounts!(docker_cmd, config)
+      return unless config["repositories"].is_a?(Array) && config["repositories"].any?
+
+      puts "📚 Configuring #{config['repositories'].count} repositories..."
+
+      # Build REPOSITORIES_CONTEXT for sessionstart hook (format: "name:path,name:path")
+      sorted_repos = config["repositories"].sort_by { |r| r["position"] || 0 }
+      repos_context = sorted_repos.map do |repo|
+        repo_name = repo["name"]
+        sandbox_path = repo["path_in_sandbox"] || "/workspace/#{repo_name}"
+        "#{repo_name}:#{sandbox_path}"
+      end.join(",")
+
+      docker_cmd.concat(["-e", "REPOSITORIES_CONTEXT=#{repos_context}"])
+
+      # Pass repository config via environment variables for container to clone
+      repo_config_json = sorted_repos.to_json
+      docker_cmd.concat(["-e", "REPOSITORIES_CONFIG=#{repo_config_json}"])
+
+      sorted_repos.each do |repo|
+        repo_name = repo["name"]
+        sandbox_path = repo["path_in_sandbox"] || "/workspace/#{repo_name}"
+        puts "   - #{repo_name}: #{sandbox_path} (will be cloned in container)"
+      end
+    end
+
     def self.add_development_mounts!(docker_cmd)
       # Check for local setup-agent.rb (for development)
       local_setup_script = File.join(File.dirname(__FILE__), "..", "..", "setup-agent.rb")
-      
+
       # Check for local agent-bridge binaries (for development)
       arch = `uname -m`.strip
       linux_arch = (arch == "x86_64") ? "amd64" : "arm64"
-      linux_bridge = File.join(Dir.pwd, "tinker-public", "bin", "agent-bridge-linux-#{linux_arch}")
-      
+
+      # Try multiple possible paths for the binary (built Go binaries in dist/)
+      possible_paths = [
+        File.join(Dir.pwd, "overrides", "agent-bridge-linux-#{linux_arch}"),              # TINKER_SANDBOX/overrides
+        File.join(Dir.pwd, "tinker-public", "dist", "agent-bridge-linux-#{linux_arch}"),  # Running from metafolder
+        File.join(Dir.pwd, "..", "tinker-public", "dist", "agent-bridge-linux-#{linux_arch}"), # Running from TINKER_SANDBOX
+        File.join(Dir.pwd, "dist", "agent-bridge-linux-#{linux_arch}"),                    # Running from tinker-public
+      ]
+
+      linux_bridge = nil
+      possible_paths.each do |path|
+        if File.exist?(path)
+          linux_bridge = path
+          break
+        end
+      end
+
       local_bridge_default = File.join(Dir.pwd, "bin", "agent-bridge")
       local_tmux = File.join(File.dirname(__FILE__), "..", "..", "bin", "agent-bridge-tmux")
-      
+
       if File.exist?(local_setup_script)
         puts "🔧 Using local setup-agent.rb for development"
         docker_cmd.concat(["-v", "#{File.expand_path(local_setup_script)}:/tmp/setup-agent.rb:ro"])
       end
 
-      if File.exist?(linux_bridge)
+      if linux_bridge && File.exist?(linux_bridge)
         puts "🔧 Using local linux binary: #{linux_bridge}"
-        docker_cmd.concat(["-v", "#{linux_bridge}:/tmp/agent-bridge:ro"])
+        docker_cmd.concat(["-v", "#{File.expand_path(linux_bridge)}:/tmp/agent-bridge:ro"])
       elsif File.exist?(local_bridge_default)
         # Check if it's a binary or script
         is_script = File.read(local_bridge_default, 4) == "#!/b"
@@ -212,7 +273,7 @@ module TinkerAgent
           docker_cmd.concat(["-v", "#{local_bridge_default}:/tmp/agent-bridge:ro"])
         end
       end
-      
+
       if File.exist?(local_tmux)
         docker_cmd.concat(["-v", "#{File.expand_path(local_tmux)}:/tmp/agent-bridge-tmux:ro"])
       end

package/lib/tinker_agent/config.rb

@@ -67,6 +67,56 @@ module TinkerAgent
       JSON.parse(JSON.generate(config))
     end
 
+    def self.fetch_repositories!(config)
+      return unless config["rails_api_url"] && config["project_id"]
+
+      # Use the first available agent's MCP API key
+      mcp_api_key = nil
+      if config["agents"].is_a?(Hash)
+        config["agents"].each do |_, agent_config|
+          if agent_config.is_a?(Hash) && agent_config["mcp_api_key"]
+            mcp_api_key = agent_config["mcp_api_key"]
+            break
+          end
+        end
+      end
+
+      return unless mcp_api_key
+
+      # Fetch repositories from Rails API
+      require "net/http"
+      require "json"
+      require "uri"
+
+      uri = URI("#{config['rails_api_url']}/projects/#{config['project_id']}/repositories")
+
+      begin
+        response = Net::HTTP.get_response(uri, { "X-API-Key" => mcp_api_key, "Accept" => "application/json" })
+
+        if response.code == "200"
+          repositories = JSON.parse(response.body)
+
+          if repositories.any?
+            config["repositories"] = repositories
+
+            # Build REPOSITORIES_CONTEXT string: "name:path,name:path"
+            repo_context = repositories.map { |r| "#{r['name']}:#{r['path_in_sandbox']}" }.join(",")
+            config["env"] ||= {}
+            config["env"]["REPOSITORIES_CONTEXT"] = repo_context
+
+            puts "📚 Loaded #{repositories.count} repositories for project #{config['project_id']}"
+            repositories.each do |repo|
+              puts "   - #{repo['name']}: #{repo['path_in_sandbox']}"
+            end
+          end
+        else
+          puts "⚠️  Unable to fetch repositories (HTTP #{response.code})"
+        end
+      rescue StandardError => e
+        puts "⚠️  Failed to fetch repositories: #{e.message}"
+      end
+    end
+
     def self.image_name(config)
       if config["project_id"]
         "tinker-sandbox-#{config['project_id']}"

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "tinker-agent",
-  "version": "1.0.56",
+  "version": "1.0.59",
   "description": "Tinker Agent Runner",
   "bin": {
-    "tinker-agent": "./run-tinker-agent.rb"
+    "tinker-agent": "./bin/run-tinker-agent.rb"
   },
   "files": [
-    "run-tinker-agent.rb",
+    "bin/run-tinker-agent.rb",
     "agents.rb",
     "setup-agent.rb",
     "lib/",
@@ -18,4 +18,4 @@
   },
   "author": "",
   "license": "ISC"
-}
+}

package/setup-agent.rb

@@ -176,14 +176,24 @@ end
 def setup_claude_config!
   home_claude_json = File.expand_path("~/.claude.json")
 
+  # First, try to copy from mounted config (from host)
+  mounted_paths = ["/tmp/cfg/claude.json"]
+  mounted_paths.each do |path|
+    if File.exist?(path) && !File.exist?(home_claude_json)
+      FileUtils.cp(path, home_claude_json)
+      puts "📋 Copied claude.json from #{path}"
+      break
+    end
+  end
+
   if File.exist?(home_claude_json)
     puts "🔧 Configuring claude.json..."
     begin
       claude_config = JSON.parse(File.read(home_claude_json))
-      
+
       # Add bypass permission at top level
       claude_config["bypassPermissionsModeAccepted"] = true
-      
+
       File.write(home_claude_json, JSON.pretty_generate(claude_config))
       puts "✅ claude.json configured with bypass permissions"
     rescue JSON::ParserError
@@ -200,9 +210,33 @@ def setup_claude_settings!
   home_settings_json = File.join(settings_dir, "settings.json")
 
   puts "🔧 Configuring ~/.claude/settings.json..."
-  
+
   settings_config = {}
-  if File.exist?(home_settings_json)
+
+  # First, try to load user's existing settings from mounted config
+  # We merge both files: settings.json AND claude.json (for theme/appearance settings)
+  mounted_settings_paths = [
+    "/tmp/cfg/settings.json",
+    "/tmp/cfg/claude.json"
+  ]
+
+  mounted_settings = {}
+  mounted_settings_paths.each do |path|
+    if File.exist?(path)
+      begin
+        file_settings = JSON.parse(File.read(path))
+        # Merge settings - later files override earlier ones for conflicting keys
+        mounted_settings = mounted_settings.merge(file_settings)
+        puts "   (loaded from #{path})"
+      rescue JSON::ParserError => e
+        puts "   ⚠️  Failed to parse #{path}: #{e.message}"
+      end
+    end
+  end
+
+  if mounted_settings.any?
+    settings_config = mounted_settings
+  elsif File.exist?(home_settings_json)
     begin
       settings_config = JSON.parse(File.read(home_settings_json))
     rescue JSON::ParserError
@@ -266,6 +300,42 @@ def setup_claude_settings!
 
   settings_config["hooks"]["SessionStart"] << session_hook_to_add
 
+  # Install sessionstart-input.sh for repository context injection
+  # This provides repository information to Claude at session start
+  input_script_name = "sessionstart-input.sh"
+  input_dest_path = File.join(hooks_dir, input_script_name)
+
+  local_input_paths = [
+    File.join(Dir.pwd, "tinker-public", "hooks", input_script_name),
+    File.join(Dir.pwd, "hooks", input_script_name)
+  ]
+
+  local_input_content = nil
+  local_input_paths.each do |path|
+    if File.exist?(path)
+      local_input_content = File.read(path)
+      puts "   (using local input hook: #{path})"
+      break
+    end
+  end
+
+  if local_input_content
+    File.write(input_dest_path, local_input_content)
+    File.chmod(0755, input_dest_path)
+    puts "✅ Installed SessionStart input hook (from local) to #{input_dest_path}"
+  else
+    puts "📥 Downloading SessionStart input hook..."
+    input_hook_url = "#{TINKER_RAW_URL}/hooks/#{input_script_name}"
+    begin
+      input_hook_content = URI.open(input_hook_url).read
+      File.write(input_dest_path, input_hook_content)
+      File.chmod(0755, input_dest_path)
+      puts "✅ Installed SessionStart input hook (from remote) to #{input_dest_path}"
+    rescue OpenURI::HTTPError => e
+      puts "⚠️  Failed to download input hook: #{e.message}"
+    end
+  end
+
   File.write(home_settings_json, JSON.pretty_generate(settings_config))
   puts "✅ ~/.claude/settings.json configured with skill hooks"
 end
@@ -277,6 +347,37 @@ def setup_system_prompt!
     puts "❌ /etc/tinker/system-prompt.txt not found!"
     exit 1
   end
+
+  # Add repository context to CLAUDE.md for easy reference
+  claude_md = File.expand_path("~/CLAUDE.md")
+  if ENV["REPOSITORIES_CONTEXT"]
+    repo_info = ENV["REPOSITORIES_CONTEXT"].split(',').map do |repo|
+      name, path = repo.split(':')
+      "  - **#{name}**: #{path}"
+    end.join("\n")
+
+    repo_context_md = <<~MARKDOWN
+      ## Repository Structure
+
+      This project has #{ENV["REPOSITORIES_CONTEXT"].split(',').count} repositories:
+
+      #{repo_info}
+
+      ### Repository Switching
+
+      Use `switch-to-repo.sh <name>` to change working directories:
+
+      ```bash
+      switch-to-repo.sh tinker
+      switch-to-repo.sh tinker-public
+      ```
+    MARKDOWN
+
+    # Append to existing CLAUDE.md or create new one
+    existing_content = File.exist?(claude_md) ? File.read(claude_md) : ""
+    File.write(claude_md, existing_content + "\n" + repo_context_md)
+    puts "📝 Repository context added to ~/CLAUDE.md"
+  end
 end
 
 
@@ -424,34 +525,124 @@ def setup_github_auth!
 
     # Configure git
     system("git config --global credential.helper '!f() { test \"$1\" = get && echo \"protocol=https\" && echo \"host=github.com\" && echo \"username=x-access-token\" && echo \"password=$(#{helper_path})\"; }; f'")
-    
-    # Configure gh CLI wrapper for auto-refresh
-    real_gh_path = "/usr/bin/gh"
-    if File.exist?(real_gh_path)
-      wrapper_path = "/usr/local/bin/gh"
-      wrapper_content = <<~BASH
-        #!/bin/bash
-        # Auto-refresh GitHub token using git-auth-helper
-        export GH_TOKEN=$(#{helper_path})
-        exec #{real_gh_path} "$@"
-      BASH
-      
-      File.write("/tmp/gh-wrapper", wrapper_content)
-      system("sudo mv /tmp/gh-wrapper #{wrapper_path}")
-      system("sudo chmod +x #{wrapper_path}")
-      puts "✅ GitHub App authentication configured (with auto-refresh)"
-    else
-      puts "⚠️  Could not find 'gh' at #{real_gh_path}, skipping wrapper"
+
+    # Configure gh CLI wrapper for auto-refresh and permission controls
+    if install_gh_wrapper!(real_gh_path: "/usr/bin/gh", with_token_refresh: true, token_helper_path: helper_path)
+      puts "✅ GitHub App authentication configured (with auto-refresh + permission controls)"
     end
 
   elsif ENV["GH_TOKEN"] && !ENV["GH_TOKEN"].empty?
     system("echo '#{ENV['GH_TOKEN']}' | gh auth login --with-token 2>/dev/null")
-    puts "🔐 GitHub authentication configured"
+
+    # Install wrapper for permission controls even with GH_TOKEN
+    if install_gh_wrapper!(real_gh_path: "/usr/bin/gh")
+      puts "🔐 GitHub authentication configured (with permission controls)"
+    else
+      puts "🔐 GitHub authentication configured"
+    end
   else
     puts "⚠️  No GH_TOKEN or GitHub App config - GitHub operations may fail"
   end
 end
 
+def install_gh_wrapper!(real_gh_path:, with_token_refresh: false, token_helper_path: nil)
+  unless File.exist?(real_gh_path)
+    puts "⚠️  Could not find 'gh' at #{real_gh_path}, skipping wrapper"
+    return false
+  end
+
+  # Move real gh to gh.real if not already done
+  unless File.exist?("#{real_gh_path}.real")
+    system("sudo mv #{real_gh_path} #{real_gh_path}.real")
+  end
+
+  wrapper_path = "/usr/local/bin/gh"
+
+  # Build token export line if auto-refresh is enabled
+  token_export = with_token_refresh ? "export GH_TOKEN=$(#{token_helper_path})\n\n" : ""
+
+  wrapper_content = <<~BASH
+    #!/bin/bash
+    # GitHub CLI wrapper with permission controls for agents
+    #{token_export}# Check if caller is an agent (read AGENT_TYPE at runtime)
+    if [ -n "$AGENT_TYPE" ] && [[ "$AGENT_TYPE" =~ ^(worker|planner|reviewer|researcher)$ ]]; then
+      # Block comment-related commands for agents
+      if [[ "$1" == "comment" ]] || ([[ "$1" == "pr" ]] && [[ "$2" == "comment" ]]); then
+        echo "❌ You cannot use 'gh $*' commands as an agent." >&2
+        echo "" >&2
+        echo "Tinker has its own comment system via the add_comment MCP tool." >&2
+        echo "Please use the add_comment tool instead of gh commands." >&2
+        echo "" >&2
+        echo "Example:" >&2
+        echo "  add_comment(ticket_id: 123, content: \\"Your comment here\\", comment_type: \\"note\\")" >&2
+        exit 1
+      fi
+    fi
+
+    # Execute real gh binary with all arguments
+    exec #{real_gh_path}.real "$@"
+  BASH
+
+  File.write("/tmp/gh-wrapper", wrapper_content)
+  system("sudo mv /tmp/gh-wrapper #{wrapper_path}")
+  system("sudo chmod +x #{wrapper_path}")
+  true
+end
+
+def clone_repositories!
+  return unless ENV["REPOSITORIES_CONFIG"]
+
+  begin
+    repos = JSON.parse(ENV["REPOSITORIES_CONFIG"])
+    return unless repos.is_a?(Array) && repos.any?
+
+    puts "📚 Cloning #{repos.count} repositories..."
+
+    repos.each do |repo|
+      repo_name = repo["name"]
+      github_url = repo["github_url"]
+      sandbox_path = repo["path_in_sandbox"] || "/workspace/#{repo_name}"
+
+      # Create parent directory if needed
+      parent_dir = File.dirname(sandbox_path)
+      FileUtils.mkdir_p(parent_dir) unless File.exist?(parent_dir)
+
+      # Clone repository if it doesn't exist
+      unless File.exist?(sandbox_path)
+        puts "   📥 Cloning #{repo_name} to #{sandbox_path}..."
+        system("git", "clone", "--depth", "1", github_url, sandbox_path)
+      else
+        puts "   ✓ #{repo_name} already exists at #{sandbox_path}"
+      end
+    end
+
+    puts "✅ Repositories cloned"
+
+    # Write repository context to a file for hooks to read
+    # This is more reliable than environment variables in tmux sessions
+    if ENV["REPOSITORIES_CONTEXT"]
+      repo_context_file = File.expand_path("~/.claude/repos_context.txt")
+      File.write(repo_context_file, ENV["REPOSITORIES_CONTEXT"])
+      puts "📝 Repository context written to #{repo_context_file}"
+    end
+
+    # Export REPOSITORIES_CONTEXT to bash profile for shell sessions
+    if ENV["REPOSITORIES_CONTEXT"]
+      profile_file = File.expand_path("~/.bashrc")
+      existing_content = File.exist?(profile_file) ? File.read(profile_file) : ""
+
+      # Remove old export if present
+      existing_content.gsub!(/^export REPOSITORIES_CONTEXT=.*$/, "")
+
+      # Add new export at the end
+      File.write(profile_file, existing_content + "\nexport REPOSITORIES_CONTEXT=\"#{ENV['REPOSITORIES_CONTEXT']}\"\n")
+      puts "📝 REPOSITORIES_CONTEXT exported to ~/.bashrc"
+    end
+  rescue JSON::ParserError => e
+    puts "⚠️  Failed to parse REPOSITORIES_CONFIG: #{e.message}"
+  end
+end
+
 def setup_git_config!
   # Configure identity if provided
   if ENV["GIT_USER_NAME"] && !ENV["GIT_USER_NAME"].empty?
@@ -514,6 +705,71 @@ def setup_git_hooks!
   puts "✅ Git hooks installed"
 end
 
+def setup_multi_repo_scripts!
+  # Install switch-to-repo.sh script and repo-specific setup scripts
+  # These are only needed when using multi-repo setup
+  repos_dir = File.expand_path("~/repos")
+  bin_dir = "/usr/local/bin"
+
+  puts "📚 Setting up multi-repo scripts..."
+
+  # Create repos directory for repo-specific setup scripts
+  FileUtils.mkdir_p(repos_dir)
+
+  # Install switch-to-repo.sh script
+  switch_script = File.join(bin_dir, "switch-to-repo.sh")
+
+  # Try local copy first, then download from GitHub
+  local_paths = [
+    File.join(Dir.pwd, "tinker-public", "hooks", "switch-to-repo.sh"),
+    File.join(Dir.pwd, "hooks", "switch-to-repo.sh"),
+    "/tmp/hooks/switch-to-repo.sh"
+  ]
+
+  script_content = nil
+  local_paths.each do |path|
+    if File.exist?(path)
+      script_content = File.read(path)
+      puts "   (from local: #{path})"
+      break
+    end
+  end
+
+  unless script_content
+    url = "#{TINKER_RAW_URL}/hooks/switch-to-repo.sh"
+    begin
+      script_content = URI.open(url).read
+    rescue OpenURI::HTTPError => e
+      puts "⚠️  Failed to download switch-to-repo.sh: #{e.message}"
+      return
+    end
+  end
+
+  # Write to temp file first, then sudo mv
+  temp_script = "/tmp/switch-to-repo.sh.temp"
+  File.write(temp_script, script_content)
+  system("sudo mv #{temp_script} #{switch_script}")
+  system("sudo chmod +x #{switch_script}")
+  puts "✅ Installed switch-to-repo.sh to #{bin_dir}"
+
+  # Install repo-specific setup scripts
+  # These are example scripts that can be customized per repository
+  local_repos_dir = File.join(Dir.pwd, "tinker-public", "repos")
+
+  if File.directory?(local_repos_dir)
+    Dir.glob(File.join(local_repos_dir, "*.sh")).each do |script_file|
+      script_name = File.basename(script_file)
+      dest_script = File.join(repos_dir, script_name)
+      FileUtils.cp(script_file, dest_script)
+      File.chmod(0755, dest_script)
+      puts "   - Installed #{script_name}"
+    end
+    puts "✅ Installed repo-specific setup scripts"
+  else
+    puts "ℹ️  No repo-specific setup scripts found (skipping)"
+  end
+end
+
 def download_agent_bridge!
   # Detect architecture
   arch = `uname -m`.strip
@@ -526,20 +782,109 @@ def download_agent_bridge!
     exit 1
   end
 
-  bridge_url = "#{TINKER_RAW_URL}/bin/agent-bridge-linux-#{arch}"
-  bridge_tmux_url = "#{TINKER_RAW_URL}/bin/agent-bridge-tmux"
   target_dir = "/usr/local/bin"
 
-  # Check if binaries are mounted at /tmp (dev mode)
+  # 1. Check for local override in /tmp/overrides (development mode)
+  override_dir = "/tmp/overrides"
+  if Dir.exist?(override_dir)
+    local_override = File.join(override_dir, "agent-bridge-linux-#{arch}")
+    if File.exist?(local_override)
+      puts "🔧 Using local override: #{local_override}"
+      system("sudo cp #{local_override} #{target_dir}/agent-bridge")
+      system("sudo chmod +x #{target_dir}/agent-bridge")
+      puts "✅ agent-bridge installed from local override"
+      return download_agent_bridge_tmux!(target_dir)
+    end
+  end
+
+  # 2. Check if binaries are mounted at /tmp (dev mode)
   if File.exist?("/tmp/agent-bridge")
     puts "🔧 Installing mounted agent-bridge..."
     system("sudo cp /tmp/agent-bridge #{target_dir}/agent-bridge")
     system("sudo chmod +x #{target_dir}/agent-bridge")
-  else
-    puts "📥 Downloading agent-bridge for linux-#{arch}..."
-    system("sudo curl -fsSL #{bridge_url} -o #{target_dir}/agent-bridge")
+    puts "✅ agent-bridge installed from mount"
+    return download_agent_bridge_tmux!(target_dir)
+  end
+
+  # 3. Try Civo bucket download (production mode)
+  if ENV["CIVO_ACCESS_KEY_ID"] && ENV["CIVO_SECRET_KEY"]
+    puts "📥 Downloading agent-bridge from Civo bucket..."
+    if download_from_civo!(arch, target_dir)
+      return download_agent_bridge_tmux!(target_dir)
+    else
+      puts "⚠️  Civo download failed, falling back to GitHub..."
+    end
+  end
+
+  # 4. Fallback to GitHub raw URLs (legacy)
+  bridge_url = "#{TINKER_RAW_URL}/bin/agent-bridge-linux-#{arch}"
+  puts "📥 Downloading agent-bridge for linux-#{arch} from GitHub..."
+  system("sudo curl -fsSL #{bridge_url} -o #{target_dir}/agent-bridge")
+  system("sudo chmod +x #{target_dir}/agent-bridge")
+
+  puts "✅ agent-bridge installed to #{target_dir}"
+  download_agent_bridge_tmux!(target_dir)
+end
+
+def download_from_civo!(arch, target_dir)
+  require "aws-sdk-s3"
+
+  region = ENV["CIVO_REGION"] || "LON1"
+  endpoint = ENV["CIVO_ENDPOINT"] || "https://objectstore.fra1.civo.com"
+  bucket = ENV["TINKER_BINARIES_BUCKET"] || "tinker"
+  version = ENV["AGENT_BRIDGE_VERSION"] || "latest"
+
+  binary_name = "agent-bridge-linux-#{arch}"
+  key = "agent-bridge/#{version}/#{binary_name}"
+
+  puts "   Region: #{region}"
+  puts "   Bucket: #{bucket}"
+  puts "   Version: #{version}"
+  puts "   Binary: #{binary_name}"
+
+  begin
+    # Configure Civo S3-compatible client
+    Aws.config.update({
+      region: region,
+      endpoint: endpoint,
+      access_key_id: ENV["CIVO_ACCESS_KEY_ID"],
+      secret_access_key: ENV["CIVO_SECRET_KEY"]
+    })
+
+    s3 = Aws::S3::Resource.new
+    obj = s3.bucket(bucket).object(key)
+
+    # Generate presigned URL (valid for 1 hour)
+    url = obj.presigned_url(:get, expires_in: 3600)
+
+    puts "✅ Generated presigned URL"
+
+    # Download via curl
+    system("sudo curl -fsSL #{url} -o #{target_dir}/agent-bridge")
+
+    unless $?.success?
+      puts "❌ Failed to download agent-bridge from Civo"
+      return false
+    end
+
     system("sudo chmod +x #{target_dir}/agent-bridge")
+    puts "✅ Downloaded agent-bridge from Civo"
+    return true
+
+  rescue LoadError
+    puts "⚠️  aws-sdk-s3 gem not installed"
+    return false
+  rescue Aws::S3::Errors::NoSuchKey
+    puts "❌ Version #{version} not found in bucket"
+    return false
+  rescue => e
+    puts "❌ Civo download failed: #{e.message}"
+    return false
   end
+end
+
+def download_agent_bridge_tmux!(target_dir)
+  bridge_tmux_url = "#{TINKER_RAW_URL}/bin/agent-bridge-tmux"
 
   if File.exist?("/tmp/agent-bridge-tmux")
     puts "🔧 Installing mounted agent-bridge-tmux..."
@@ -549,8 +894,6 @@ def download_agent_bridge!
     system("sudo curl -fsSL #{bridge_tmux_url} -o #{target_dir}/agent-bridge-tmux")
     system("sudo chmod +x #{target_dir}/agent-bridge-tmux")
   end
-
-  puts "✅ agent-bridge installed to #{target_dir}"
   
   # Patch agent-bridge-tmux to force INSIDE_TMUX=1
   # Note: This is now fixed in the repo, but we keep this for backward compatibility
@@ -602,14 +945,17 @@ puts ""
 check_env!
 fetch_agent_id!
 setup_mcp_config!
+setup_system_prompt!
+# Clone repositories BEFORE setting up hooks that depend on them
+setup_github_auth!
+setup_git_config!
+clone_repositories!
 setup_claude_config!
 setup_claude_settings!
-setup_system_prompt!
 # setup_skill_hooks! # Deprecated in favor of global hooks
 setup_skills!
-setup_github_auth!
-setup_git_config!
 setup_git_hooks!
+setup_multi_repo_scripts!
 # prepare_git_state! is now in entrypoint.sh
 bin_dir = download_agent_bridge!
 run_agent!(bin_dir)