rubyn-code 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f91f304118c243f82ce9165db84f303b111d9c18daf74c75cdc7dcec4289647b
-  data.tar.gz: 2cfc8263c1532d805ea9b9592c3601033e4fdab8dc19c6b0329a0eec40316cbb
+  metadata.gz: 342d51b0944ce35908b8fd56f52b0321cf698ea01ec3cc8fa572d92b9c332b22
+  data.tar.gz: '033868c98fedc4814cb9e8c94eb8f013b15641d5a3e7cecf7e819d3d3b57f771'
 SHA512:
-  metadata.gz: 6bb339794d0cbe8d149e0b2e94c408b304d48f786aa2a297af5c8028c15c9796d4e5f0313be20c1ecf8b449c0ef80afa4263f581603c5c915b540c7a89b8257c
-  data.tar.gz: 2f1fc37549f2223a5c5f07be4817bade9a4d6466ef30b8927fb0de94cf4c78c41b1b5e9e8a3379fb69e503d34226df9d22e4988bb45231666afc49e4f325d789
+  metadata.gz: 283cff44827418497c9ed9d27e4331d8fdf24c04825ee3f28e46a33da28bf61f65d0a2b85173187947393856053fad5466dce5782fcef3d0e1dcce68d37e00eb
+  data.tar.gz: 6c96e7beba37f74c0fe947470a1a37d50b521087b573407d6ba7d0d0649d71385b263b70b126fe9c2b7da3c910a233862fdbfb8c1d7c534db6f6cc1d813ec305

data/README.md

@@ -22,12 +22,49 @@ Refactor controllers, generate idiomatic RSpec, catch N+1 queries, review code f
 
 > **Rubyn is going open source.** The original [Rubyn gem](https://github.com/Rubyn-AI/rubyn) provided AI-assisted refactoring, spec generation, and code review through the Rubyn API. **Rubyn Code** is the next evolution — a complete agentic coding assistant that runs locally, thinks for itself, and learns from every session. No API keys. No separate billing. Just `gem install rubyn-code` and go.
 
+---
+
+## Table of Contents
+
+- [Why Rubyn?](#why-rubyn)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [What Can Rubyn Do?](#what-can-rubyn-do)
+- [VS Code Extension](#vs-code-extension)
+- [29 Built-in Tools](#29-built-in-tools)
+- [MCP — External Tool Servers](#mcp--external-tool-servers)
+- [Codebase Indexing](#codebase-indexing)
+- [112 Best Practice Skills](#112-best-practice-skills)
+- [Context Architecture](#context-architecture)
+- [RUBYN.md — Project Instructions](#rubynmd--project-instructions)
+- [PR Review](#pr-review)
+- [Sub-Agents & Teams](#sub-agents--teams)
+- [GOLEM — Autonomous Daemon](#golem--autonomous-daemon)
+- [Continuous Learning](#continuous-learning)
+- [Streaming Output](#streaming-output)
+- [Search Providers](#search-providers)
+- [User Hooks](#user-hooks)
+- [CLI Reference](#cli-reference)
+- [Authentication](#authentication)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+- [Security](#security)
+- [Diagnostics](#diagnostics)
+- [Development](#development)
+- [From Rubyn to Rubyn Code](#from-rubyn-to-rubyn-code)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
 ## Why Rubyn?
 
 - **Rails-native** — understands service object extraction, RSpec conventions, ActiveRecord patterns, and Hotwire
 - **Context-aware** — automatically incorporates schema, routes, specs, factories, and models
 - **Best practices built in** — ships with 112 curated Ruby and Rails guidelines that load on demand
 - **Agentic** — doesn't just answer questions. Reads files, writes code, runs specs, commits, reviews PRs, spawns sub-agents, and remembers what it learns
+- **IDE-ready** — works in the terminal and inside VS Code with full bidirectional communication
+- **Extensible** — connect external tool servers via MCP, add custom skills, or wire up your own providers
 
 ## Install
 
@@ -93,6 +130,9 @@ rubyn-code --yolo
 
 # Single prompt
 rubyn-code -p "Refactor app/controllers/orders_controller.rb into service objects"
+
+# VS Code IDE mode (used by the extension)
+rubyn-code --ide
 ```
 
 ## What Can Rubyn Do?
@@ -118,7 +158,7 @@ rubyn > Write specs for the new service objects
   > write_file: path=spec/services/orders/create_service_spec.rb
   > run_specs: path=spec/services/orders/
 
-4 examples, 0 failures. All green. ✓
+4 examples, 0 failures. All green.
 ```
 
 ### Review code
@@ -142,6 +182,29 @@ Agent finished (23 tool calls).
 This is a Rails 7.1 e-commerce app with...
 ```
 
+## VS Code Extension
+
+Rubyn Code includes a VS Code extension that provides a full IDE experience with bidirectional JSON-RPC communication. The extension runs Rubyn as a subprocess and connects over stdin/stdout.
+
+**Capabilities:**
+
+- Chat panel with streaming responses and syntax-highlighted code blocks
+- Inline diffs — review and accept generated code changes directly in the editor
+- Tool approval prompts in the IDE (or skip them in YOLO mode)
+- Full session management — resume, list, fork, and reset conversations
+- Structured code review feedback with severity ratings
+- IDE config get/set for persistent settings
+- All 29 tools available, including MCP tools
+
+**Permission modes:**
+
+| Mode | Behavior |
+|------|----------|
+| `default` | Per-tool approval required |
+| `bypass` | YOLO — skip all approval prompts |
+
+The extension communicates over 14 RPC methods: `initialize`, `prompt`, `cancel`, `review`, `approveToolUse`, `acceptEdit`, `session/*`, `config/*`, `models/list`, and `shutdown`.
+
 ## 29 Built-in Tools
 
 | Category | Tools |
@@ -159,6 +222,58 @@ This is a Rails 7.1 e-commerce app with...
 | **Teams** | `send_message`, `read_inbox` |
 | **Interactive** | `ask_user` (ask clarifying questions mid-task) |
 
+## MCP — External Tool Servers
+
+Connect external tool servers via the [Model Context Protocol](https://modelcontextprotocol.io). MCP tools are dynamically discovered and registered as native Rubyn tools, available in the REPL, IDE, and daemon.
+
+### Configuration
+
+Create `.rubyn-code/mcp.json` in your project or `~/.rubyn-code/mcp.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
+    },
+    "my-api": {
+      "url": "http://localhost:3001/mcp",
+      "timeout": 30
+    }
+  }
+}
+```
+
+- **Stdio transport** — specify `command` and `args` to run a subprocess
+- **SSE transport** — specify `url` for HTTP-based servers
+- Environment variables are interpolated with `${VAR}` syntax
+
+MCP tools appear in the tool palette prefixed with `mcp_` and require confirmation before execution. Run `/doctor` to verify server connectivity.
+
+Rubyn ships with three example MCP servers: **database explorer**, **RubyGems lookup**, and **Rails routes**. See `/mcp` for documentation.
+
+## Codebase Indexing
+
+Rubyn builds a structural index of your codebase on first session and incrementally updates it as files change. The index powers smarter context injection, skill suggestions, and impact analysis.
+
+**What it tracks:**
+
+- Classes, modules, methods, callbacks, scopes, validations, associations
+- Relationships between files (associations, test coverage, caller/callee)
+- Rails patterns: `has_many`, `belongs_to`, `before_action`, `validates`, etc.
+- File classification: model, controller, service, concern, spec
+
+**How it's used:**
+
+- Injects a compact structural summary into the system prompt
+- Feeds the dynamic tool schema for smarter tool selection
+- Powers `impact_analysis(file)` to find affected tests and dependents
+- Suggests relevant skills based on the code you're working with
+
+Stored at `.rubyn-code/codebase_index.json`. The `/doctor` command flags stale indexes (>24 hours).
+
 ## 112 Best Practice Skills
 
 Rubyn ships with curated best practice documents that load on demand. Only skill names are in memory — full content loads when Rubyn needs it.
@@ -176,6 +291,17 @@ Rubyn ships with curated best practice documents that load on demand. Only skill
 | **Gems** | Sidekiq, Devise, FactoryBot, Pundit, Faraday, Stripe, RuboCop, dry-rb |
 | **Sinatra** | Application structure, middleware, testing |
 
+### Skill search & filter
+
+```
+rubyn > /skill search factory      # search by name, description, or tags
+rubyn > /skill list rails          # filter by category
+rubyn > /skill list                # show all categories
+rubyn > /skill load rspec_matchers # inject a skill into context
+```
+
+Results are relevance-ranked: name matches score highest, then description, then tags.
+
 ### Custom skills
 
 Override or extend with your own:
@@ -199,6 +325,8 @@ Rubyn automatically loads relevant context based on what you're working on:
 - **Service objects** → includes referenced models and their specs
 - **Any file** → checks for `RUBYN.md`, `CLAUDE.md`, or `AGENT.md` instructions
 
+The [codebase index](#codebase-indexing) enhances this with structural awareness — Rubyn knows which files depend on each other before it reads them.
+
 ## RUBYN.md — Project Instructions
 
 Drop a `RUBYN.md` in your project root and Rubyn follows your conventions:
@@ -259,6 +387,32 @@ rubyn > Send alice a message to write specs for the User model
 
 Teammates run in background threads with their own agent loop and mailbox.
 
+## GOLEM — Autonomous Daemon
+
+GOLEM is an always-on autonomous agent that claims tasks from a queue and works through them independently. It runs a full agent loop per task with access to all tools, MCP servers, and memory.
+
+```bash
+rubyn-code daemon \
+  --name golem-1 \
+  --role "Backend Engineer" \
+  --max-runs 100 \
+  --max-cost 10.0 \
+  --poll-interval 5 \
+  --idle-timeout 60
+```
+
+**Lifecycle:** `spawned → working ⇄ idle → shutting_down → stopped`
+
+**Safety limits:**
+
+| Guard | Description |
+|-------|-------------|
+| `--max-runs` | Auto-shutdown after N completed tasks |
+| `--max-cost` | Stop when cumulative USD spend exceeds limit |
+| **Retry backoff** | 3 retries per task before marking failed |
+| **Audit trail** | Full conversation saved per task via session persistence |
+| **Cost tracking** | Accurate per-task spend via the observability layer |
+
 ## Continuous Learning
 
 Rubyn gets smarter with every session:
@@ -310,12 +464,14 @@ post_tool_use:
 rubyn-code                    # Interactive REPL
 rubyn-code --yolo             # Auto-approve all tools
 rubyn-code -p "prompt"        # Single prompt, exit when done
+rubyn-code --ide              # IDE server mode (JSON-RPC over stdin/stdout)
 rubyn-code --resume [ID]      # Resume previous session
 rubyn-code --setup            # Pin to this Ruby (run once after install)
 rubyn-code --debug            # Enable debug output
 rubyn-code --auth             # Authenticate with Claude
 rubyn-code --version          # Show version
 rubyn-code --help             # Show help
+rubyn-code daemon [OPTIONS]   # Run GOLEM autonomous daemon
 ```
 
 ### Slash Commands
@@ -331,8 +487,12 @@ rubyn-code --help             # Show help
 | `/cost` | Show token usage and costs |
 | `/tasks` | List all tasks |
 | `/budget [amt]` | Show or set session budget |
-| `/skill [name]` | Load or list available skills |
+| `/skill [name]` | Load, search, or list available skills |
 | `/resume [id]` | Resume or list sessions |
+| `/provider` | Add or list providers |
+| `/model` | Show/switch model and provider |
+| `/doctor` | Run environment health checks |
+| `/mcp` | MCP server documentation and status |
 
 ## Authentication
 
@@ -354,14 +514,50 @@ export OPENAI_API_KEY=sk-...
 
 Available models: `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-4o`, `gpt-4o-mini`, `o3`, `o4-mini`
 
-### OpenAI-Compatible Providers (Groq, Together, Ollama, etc.)
+### Other Providers (Groq, Together, Ollama, etc.)
 
-Set the provider-specific API key and configure via `config.yml`:
+Add a provider and its API key in one command:
 
 ```bash
-export GROQ_API_KEY=gsk-...
+/provider add groq https://api.groq.com/openai/v1 --key gsk-xxx --models llama-3.3-70b
+
+# For Anthropic-format proxies (e.g., Bedrock, custom gateways)
+/provider add my-proxy https://proxy.example.com/v1 --format anthropic --key sk-xxx --models claude-sonnet-4-6
+
+# Update a key later
+/provider set-key groq gsk-new-key
+
+# List configured providers
+/provider list
 ```
 
+API keys are **encrypted at rest** using AES-256-GCM. The encryption key is derived from
+your machine identity (username, hostname, home directory) via PBKDF2, so keys are only
+decryptable on the same machine by the same user. Rubyn decrypts them automatically at
+runtime and re-encrypts on save — no manual steps required.
+
+Keys stored via environment variables (`GROQ_API_KEY`, `TOGETHER_API_KEY`, etc.) also work
+as a fallback if you prefer that approach.
+
+Or add directly to `~/.rubyn-code/config.yml`:
+
+```yaml
+providers:
+  groq:
+    base_url: https://api.groq.com/openai/v1
+    env_key: GROQ_API_KEY
+    models:
+      top: llama-3.3-70b
+  my-proxy:
+    api_format: anthropic        # 'openai' (default) or 'anthropic'
+    base_url: https://proxy.example.com/v1
+    env_key: PROXY_API_KEY
+    models:
+      top: claude-sonnet-4-6
+```
+
+Then switch with `/model groq:llama-3.3-70b`.
+
 Local providers (Ollama, LM Studio) running on `localhost`/`127.0.0.1` don't require an API key.
 
 ## Architecture
@@ -391,30 +587,21 @@ Local providers (Ollama, LM Studio) running on `localhost`/`127.0.0.1` don't req
 
 ## Configuration
 
+The `provider` and `model` keys at the top set the **default provider and model** used at startup.
+These must match a provider defined in the `providers` section (or a built-in like `anthropic`/`openai`).
+
 ```yaml
 # ~/.rubyn-code/config.yml (global)
-model: claude-opus-4-6
+provider: anthropic              # default provider on startup
+model: claude-opus-4-6           # default model on startup
 permission_mode: allow_read
 session_budget: 5.00
 daily_budget: 10.00
 
 # .rubyn-code/config.yml (project — overrides global)
-model: claude-sonnet-4-6
+provider: minimax                # this project uses MiniMax by default
+model: MiniMax-M2.7-highspeed
 permission_mode: autonomous
-
-# Use OpenAI instead of Anthropic
-# provider: openai
-# model: gpt-4o
-
-# Use an OpenAI-compatible provider
-# provider: groq
-# provider_base_url: https://api.groq.com/openai/v1
-# model: llama-3.3-70b
-
-# Local Ollama (no API key needed)
-# provider: ollama
-# provider_base_url: http://localhost:11434/v1
-# model: llama3
 ```
 
 ### Multi-Provider Model Routing
@@ -469,6 +656,55 @@ providers:
 
 You can also set custom pricing per model so `/cost` reports accurate spending for third-party providers.
 
+## Security
+
+### Credential Storage
+
+All provider API keys are encrypted at rest using **AES-256-GCM** (authenticated encryption).
+Keys are never stored as plaintext on disk.
+
+| Layer | Detail |
+|-------|--------|
+| **Cipher** | AES-256-GCM (authenticated — detects tampering) |
+| **Key derivation** | PBKDF2-HMAC-SHA256, 100,000 iterations |
+| **Machine binding** | Key derived from username + hostname + home directory |
+| **Salt** | Random 32-byte salt, generated once, stored in `~/.rubyn-code/.encryption_salt` |
+| **File permissions** | `tokens.yml` and `.encryption_salt` are `0600` (owner read/write only) |
+
+This means:
+- Keys copied to another machine or user account cannot be decrypted
+- The encryption key is never stored — it is derived at runtime
+- Plaintext keys from older versions are automatically encrypted on first read
+
+### File Permissions
+
+| File | Permissions | Contents |
+|------|------------|----------|
+| `~/.rubyn-code/` | `0700` | Home directory |
+| `~/.rubyn-code/tokens.yml` | `0600` | Encrypted API keys, OAuth tokens |
+| `~/.rubyn-code/.encryption_salt` | `0600` | PBKDF2 salt (not secret alone, but protected) |
+| `~/.rubyn-code/config.yml` | `0600` | Provider config (no secrets) |
+
+## Diagnostics
+
+Run `/doctor` to check your environment:
+
+```
+rubyn > /doctor
+
+✓ Ruby version         4.0.2
+✓ Bundler              installed
+✓ Database             12 migrations applied
+✓ Authentication       valid (keychain)
+✓ Skills               112 available
+✓ Project detected     Rails 7.1
+✓ MCP servers          2 connected
+✓ Codebase index       fresh (2 hours ago)
+✓ Skill catalog        112 skills, 0 malformed
+```
+
+Checks Ruby version, bundler, database state, authentication, skills, project type, MCP server connectivity, codebase index freshness, and skill catalog integrity.
+
 ## Development
 
 Requires Ruby 4.0+.
@@ -480,6 +716,12 @@ bundle install
 bundle exec rspec
 ```
 
+Quick rebuild from source:
+
+```bash
+bin/dev-install
+```
+
 ## From Rubyn to Rubyn Code
 
 If you used the original [Rubyn gem](https://github.com/Rubyn-AI/rubyn), here's what changed:

data/db/migrations/013_add_failed_status_to_tasks.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Expands the tasks CHECK constraint on status to include 'failed',
+# used by the GOLEM daemon to mark tasks that have exceeded max retries.
+#
+# SQLite does not support ALTER CONSTRAINT, so we rebuild the table.
+# The Migrator already wraps .up in a transaction — no manual BEGIN/COMMIT here.
+module Migration013AddFailedStatusToTasks
+  module_function
+
+  def up(db)
+    create_new_tasks_table(db)
+    migrate_data(db)
+    swap_tables(db)
+  end
+
+  def create_new_tasks_table(db)
+    db.execute(<<~SQL)
+      CREATE TABLE tasks_new (
+        id TEXT PRIMARY KEY,
+        session_id TEXT REFERENCES sessions(id) ON DELETE SET NULL,
+        title TEXT NOT NULL,
+        description TEXT,
+        status TEXT NOT NULL DEFAULT 'pending'
+          CHECK(status IN ('pending','in_progress','blocked','completed','cancelled','failed')),
+        priority INTEGER NOT NULL DEFAULT 0,
+        owner TEXT,
+        result TEXT,
+        metadata TEXT DEFAULT '{}',
+        created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
+        updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now'))
+      )
+    SQL
+  end
+
+  def migrate_data(db)
+    db.execute(<<~SQL)
+      INSERT INTO tasks_new (id, session_id, title, description, status, priority, owner, result, metadata, created_at, updated_at)
+      SELECT id, session_id, title, description, status, priority, owner, result, metadata, created_at, updated_at
+      FROM tasks
+    SQL
+  end
+
+  def swap_tables(db)
+    db.execute('DROP TABLE tasks')
+    db.execute('ALTER TABLE tasks_new RENAME TO tasks')
+    db.execute('CREATE INDEX IF NOT EXISTS idx_tasks_session ON tasks(session_id)')
+    db.execute('CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status)')
+    db.execute('CREATE INDEX IF NOT EXISTS idx_tasks_owner ON tasks(owner)')
+  end
+end

data/lib/rubyn_code/agent/conversation.rb

@@ -126,19 +126,48 @@ module RubynCode
 
       # Ensure every tool_use block has a matching tool_result.
       # If a tool_use is orphaned (e.g. from Ctrl-C interruption),
-      # inject a synthetic tool_result so the API doesn't reject the request.
+      # inject a synthetic tool_result immediately after the assistant
+      # message that contains the orphaned tool_use.
       def repair_orphaned_tool_uses(formatted)
         orphaned = collect_tool_use_ids(formatted) - collect_tool_result_ids(formatted)
         return formatted if orphaned.empty?
 
-        orphan_results = orphaned.map do |id|
+        insert_orphan_results(formatted, orphaned)
+      end
+
+      # Walk backwards to find the assistant message containing each orphaned
+      # tool_use and insert a user/tool_result message right after it.
+      # -- walks messages to find insertion point
+      def insert_orphan_results(formatted, orphaned)
+        orphan_set = orphaned.to_a.to_set
+        insert_idx = find_orphan_insert_index(formatted, orphan_set)
+
+        results = orphaned.map do |id|
           { type: 'tool_result', tool_use_id: id, content: '[interrupted]', is_error: true }
         end
 
-        formatted << { role: 'user', content: orphan_results }
+        formatted.insert(insert_idx, { role: 'user', content: results })
         formatted
       end
 
+      # Find the index right after the last assistant message that contains
+      # any of the orphaned tool_use IDs.
+      def find_orphan_insert_index(formatted, orphan_set)
+        formatted.each_with_index.reverse_each do |msg, idx|
+          next unless msg[:role] == 'assistant' && msg[:content].is_a?(Array)
+          return idx + 1 if assistant_has_orphan?(msg, orphan_set)
+        end
+
+        formatted.length # fallback: append at end
+      end
+
+      def assistant_has_orphan?(msg, orphan_set)
+        msg[:content].any? do |block|
+          block.is_a?(Hash) && block_matches_type?(block, 'tool_use') &&
+            orphan_set.include?(block[:id] || block['id'])
+        end
+      end
+
       def collect_tool_use_ids(formatted)
         collect_block_ids(formatted, role: 'assistant', type: 'tool_use', id_key: :id, id_str_key: 'id')
       end
@@ -148,7 +177,8 @@ module RubynCode
                                      id_str_key: 'tool_use_id')
       end
 
-      def collect_block_ids(formatted, role:, type:, id_key:, id_str_key:) # rubocop:disable Metrics/CyclomaticComplexity -- iterates blocks with type+role guards
+      # -- iterates blocks with type+role guards
+      def collect_block_ids(formatted, role:, type:, id_key:, id_str_key:)
         ids = Set.new
         formatted.each do |msg|
           next unless msg[:role] == role && msg[:content].is_a?(Array)

data/lib/rubyn_code/agent/dynamic_tool_schema.rb

@@ -31,8 +31,10 @@ module RubynCode
         #
         # @param task_context [Symbol, nil] detected task type
         # @param discovered_tools [Set<String>] tools already discovered this session
+        # @param codebase_index [RubynCode::Index::CodebaseIndex, nil] optional index for deeper context detection
+        # @param message [String, nil] original user message for index-based matching
         # @return [Array<String>] tool names to include in the schema
-        def active_tools(task_context: nil, discovered_tools: Set.new)
+        def active_tools(task_context: nil, discovered_tools: Set.new, codebase_index: nil, message: nil)
           tools = BASE_TOOLS.dup
 
           # Always include interaction tools
@@ -45,6 +47,12 @@ module RubynCode
             tools.concat(context_tools)
           end
 
+          # Add index-aware tools when a codebase index and message are available
+          if codebase_index && message
+            index_contexts = detect_index_contexts(message, codebase_index)
+            index_contexts.each { |ctx| tools.concat(resolve_context_tools(ctx)) }
+          end
+
           # Always include previously discovered tools
           tools.concat(discovered_tools.to_a)
 
@@ -54,8 +62,10 @@ module RubynCode
         # Detect task context from a user message.
         #
         # @param message [String]
+        # @param codebase_index [RubynCode::Index::CodebaseIndex, nil] optional index for deeper detection
         # @return [Symbol, nil]
-        def detect_context(message) # rubocop:disable Metrics/CyclomaticComplexity -- context detection dispatch
+        # -- context detection dispatch
+        def detect_context(message, codebase_index: nil)
           msg = message.to_s.downcase
           return :testing if msg.match?(/\b(test|spec|rspec)\b/)
           return :git     if msg.match?(/\b(commit|push|diff|branch|merge|git)\b/)
@@ -65,7 +75,27 @@ module RubynCode
           return :explore if msg.match?(/\b(explore|architecture|structure)\b/)
           return :teams   if msg.match?(/\b(team|spawn|message|inbox)\b/)
 
-          nil
+          # Fall back to index-based detection when keyword matching yields nothing
+          return nil unless codebase_index
+
+          index_contexts = detect_index_contexts(message, codebase_index)
+          index_contexts.first
+        end
+
+        # Detect additional tool contexts based on codebase index content.
+        #
+        # @param message [String] user message
+        # @param codebase_index [RubynCode::Index::CodebaseIndex] codebase index instance
+        # @return [Array<Symbol>] detected context symbols
+        def detect_index_contexts(message, codebase_index)
+          contexts = []
+          return contexts unless codebase_index
+
+          contexts << :rails if message_mentions_model?(message, codebase_index)
+          contexts << :testing if message_mentions_specced_file?(message, codebase_index)
+          contexts.uniq
+        rescue StandardError
+          []
         end
 
         # Filter full tool definitions to only include active tools.
@@ -93,6 +123,30 @@ module RubynCode
             []
           end
         end
+
+        # Check if the user message mentions a model name from the index.
+        def message_mentions_model?(message, codebase_index)
+          model_names = codebase_index.nodes
+                                      .select { |n| n['type'] == 'model' }
+                                      .map { |n| n['name'] }
+          return false if model_names.empty?
+
+          msg_lower = message.to_s.downcase
+          model_names.any? { |name| msg_lower.include?(name.downcase) }
+        end
+
+        # Check if the user message mentions a file that has specs in the index.
+        def message_mentions_specced_file?(message, codebase_index)
+          spec_edges = codebase_index.edges.select { |e| e['relationship'] == 'tests' }
+          return false if spec_edges.empty?
+
+          tested_files = spec_edges.map { |e| e['to'] }.compact
+          msg_lower = message.to_s.downcase
+          tested_files.any? do |file|
+            basename = File.basename(file, '.rb')
+            msg_lower.include?(basename)
+          end
+        end
       end
     end
   end

data/lib/rubyn_code/agent/llm_caller.rb

@@ -43,7 +43,10 @@ module RubynCode
       # Only returns models from the active provider — never crosses
       # provider boundaries (e.g., won't send a GPT model to Anthropic).
       # Falls back to nil (use client's default) if routing fails.
+      # -- guard clauses for provider/mode checks
       def routed_model
+        return nil if manual_model_mode?
+
         last_user = last_user_message_text
         return nil unless last_user
 
@@ -60,6 +63,12 @@ module RubynCode
         nil
       end
 
+      def manual_model_mode?
+        Config::Settings.new.get('model_mode', 'auto') == 'manual'
+      rescue StandardError
+        false
+      end
+
       def last_user_message_text
         msg = @conversation.messages.reverse_each.find { |m| m[:role] == 'user' }
         return nil unless msg
@@ -68,7 +77,8 @@ module RubynCode
         content.is_a?(String) ? content : nil
       end
 
-      def log_llm_call(opts) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity -- safe accessor checks
+      # -- safe accessor checks
+      def log_llm_call(opts)
         default_model = @llm_client.respond_to?(:model) ? @llm_client.model : 'default'
         routed = opts[:model]
         effective = routed || default_model