rails_claude 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cc6cc5ba06b613ea5acd963515c72379e70a66b44a3630516eb6d7c0024f3fba
+  data.tar.gz: e63ce9f4d1bb3463bc2bfe5cdeb26d58deff4a89cd5a5adfd71a1f481312de59
+SHA512:
+  metadata.gz: ff92166206f737689fe2e8c9a7344affeb03583c7bc367796709fbf298cfa0ed2b88a664564ccf7f4d6ebab592d1aa8f52ad3f49c851bd4d531759fcdc8dba0b
+  data.tar.gz: c2f7df20a83a1a292204bf4cb456a62f37fc94cf467f94fa93fe31c3a8796a776b241d775096320383dc1906d575301e4447a383b90c46e4c8f9d45383370679

data/LICENSE.txt

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026 Nick Pendery
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

data/README.md

@@ -0,0 +1,270 @@
+# RailsClaude
+
+Chat with Claude AI directly inside your Rails console, with automatic Rails context.
+
+RailsClaude drops an AI assistant into `rails c` that already knows your app's models, environment, and Ruby/Rails versions. Ask questions in plain English, get back ActiveRecord queries, debugging help, and code you can auto-execute — all without leaving the REPL.
+
+## Installation
+
+Add the gem to your development group:
+
+```ruby
+group :development do
+  gem "rails_claude"
+end
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### Requirements
+
+- Ruby 3.0+
+- Rails 6.0+
+- An [Anthropic API key](https://console.anthropic.com/)
+
+## Configuration
+
+Set your API key as an environment variable:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### Optional Configuration
+
+Create an initializer at `config/initializers/rails_claude.rb` to customize behavior:
+
+```ruby
+RailsClaude.configure do |config|
+  config.api_key    = ENV["ANTHROPIC_API_KEY"]   # default
+  config.model      = "claude-opus-4-6"          # default
+  config.max_tokens = 1024                        # default
+  config.safe_mode  = Rails.env.production?       # default
+  config.system_prompt = "Custom system prompt..." # auto-generated by default
+end
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `api_key` | `ENV["ANTHROPIC_API_KEY"]` | Your Anthropic API key |
+| `model` | `"claude-opus-4-6"` | Claude model to use for requests |
+| `max_tokens` | `1024` | Maximum tokens per response |
+| `safe_mode` | `true` in production, `false` otherwise | Wrap code execution in a rolled-back transaction |
+| `system_prompt` | Auto-generated | System prompt with Rails context (see below) |
+
+#### Auto-generated System Prompt
+
+By default, RailsClaude builds a system prompt that includes:
+
+- Your application name
+- All detected model classes (ApplicationRecord descendants)
+- Current Rails environment
+- Ruby and Rails versions
+
+This gives Claude immediate awareness of your app's structure without any manual setup.
+
+## Usage
+
+When you start `rails c`, RailsClaude loads automatically and prints available commands:
+
+```
+✦ RailsClaude ready. (safe mode)
+  claude "question"            — chat
+  claude_run! "question"       — chat + auto-eval code
+  claude_load_model User       — load a model for analysis
+  claude_load_file "path/to/f" — load any file for analysis
+  claude_safe_mode! / claude_unsafe_mode!
+  claude_history / claude_reset!
+```
+
+### `claude` — Ask a Question
+
+Send a message to Claude and get a response. Conversation history is maintained across calls, so follow-up questions work naturally.
+
+```ruby
+claude "find users who signed up in the last 7 days"
+claude "now filter those to only verified accounts"
+claude "what indexes would speed that query up?"
+```
+
+### `claude_run!` — Ask and Auto-Execute Code
+
+Like `claude`, but automatically extracts Ruby code blocks from Claude's response, executes them in the console, and feeds the result back. Runs up to 3 iterations by default (configurable via `max_iterations`).
+
+```ruby
+claude_run! "how many orders are in pending state?"
+# Claude responds with: Order.where(status: "pending").count
+# ⚡ Running: Order.where(status: "pending").count
+# ⮕ Result: 42
+
+claude_run! "show me the 5 most recent users", max_iterations: 1
+```
+
+Code is displayed in yellow before execution, and results appear in green. If the executed code raises an error, the error is captured and sent back to Claude for debugging context.
+
+### `claude_load_model` — Load a Model for Analysis
+
+Inject a model's full source code into the conversation so Claude can analyze it.
+
+```ruby
+claude_load_model User
+claude_load_model "Post"  # string names work too
+
+claude "what validations does this model have?"
+claude "find any N+1 query risks in the associations"
+```
+
+The gem finds the source file via `source_location` on the model's instance methods, falling back to `app/models/<name>.rb`.
+
+### `claude_load_file` — Load Any File for Analysis
+
+Inject any file in your project into the conversation context.
+
+```ruby
+claude_load_file "app/services/billing_service.rb"
+claude_load_file "config/routes.rb"
+
+claude "walk me through the billing flow"
+```
+
+Paths are resolved relative to `Rails.root`.
+
+### `claude_history` — View Conversation History
+
+Display all messages in the current session. User messages appear in cyan, Claude's responses in magenta.
+
+```ruby
+claude_history
+```
+
+### `claude_safe_mode!` / `claude_unsafe_mode!` — Toggle Safe Mode
+
+Switch between safe and unrestricted modes during a session without restarting the console.
+
+```ruby
+claude_unsafe_mode!
+# ⚠ Safe mode disabled — code will execute with full write access.
+
+claude_run! "create a test user"  # this will persist
+
+claude_safe_mode!
+# 🔒 Safe mode enabled — code runs in rolled-back transactions.
+```
+
+`claude_safe_mode!` also accepts a boolean: `claude_safe_mode!(false)` is equivalent to `claude_unsafe_mode!`.
+
+### `claude_reset!` — Clear History
+
+Start a fresh conversation. Clears all message history while keeping your configuration.
+
+```ruby
+claude_reset!
+```
+
+### `claude_session` — Access the Session Object
+
+For advanced usage, access the underlying `RailsClaude::Session` instance directly.
+
+```ruby
+session = claude_session
+session.history  # inspect raw conversation history
+```
+
+## Examples
+
+### Exploring Data
+
+```ruby
+claude_run! "how many users signed up this month?"
+claude_run! "show me the top 10 by order count"
+claude_run! "what's the average order value for those users?"
+```
+
+### Debugging a Model
+
+```ruby
+claude_load_model Order
+claude "what happens when status transitions from pending to fulfilled?"
+claude "are there any callbacks that could cause side effects?"
+```
+
+### Analyzing a Service
+
+```ruby
+claude_load_file "app/services/payment_service.rb"
+claude_load_file "app/models/payment.rb"
+claude "what error cases does the payment service handle?"
+claude_run! "show me an example of calling the main method"
+```
+
+### Multi-Step Investigation
+
+```ruby
+claude "are there any orders stuck in processing for more than 24 hours?"
+claude_run! "find them"
+claude_run! "show me the associated user for the oldest one"
+claude "what should I check to debug this?"
+```
+
+## Safe Mode
+
+Safe mode prevents `claude_run!` from making any persistent changes to your database. When enabled, all auto-executed code runs inside a database transaction that is **always rolled back** after the result is captured. Read queries work normally; writes are silently undone.
+
+Safe mode is **on by default in production** and off in development/test. You'll see the current mode in the startup banner:
+
+```
+✦ RailsClaude ready. (safe mode)
+```
+
+or:
+
+```
+✦ RailsClaude ready. (unrestricted)
+```
+
+The system prompt also instructs Claude to only generate read-only code when safe mode is active.
+
+### Overriding Safe Mode
+
+```ruby
+# Force safe mode on in development
+RailsClaude.configure do |config|
+  config.safe_mode = true
+end
+
+# Disable safe mode in production (use with caution)
+RailsClaude.configure do |config|
+  config.safe_mode = false
+end
+```
+
+### What Safe Mode Protects Against
+
+- `INSERT`, `UPDATE`, `DELETE` statements — rolled back after execution
+- `ActiveRecord` create/update/destroy calls — rolled back after execution
+- Claude is prompted to avoid generating destructive code entirely
+
+### What Safe Mode Does Not Protect Against
+
+- Non-database side effects (file I/O, HTTP requests, system commands)
+- Schema changes (`ALTER TABLE`, migrations) — these may auto-commit depending on your database
+
+For full isolation in production, consider restricting the database user's permissions as well.
+
+## How It Works
+
+RailsClaude uses a Rails [Railtie](https://api.rubyonrails.org/classes/Rails/Railtie.html) to hook into console startup. When `rails c` loads:
+
+1. **Eager loads** the application to discover all model classes
+2. **Creates a session** with an Anthropic API client and auto-generated system prompt
+3. **Defines helper methods** (`claude`, `claude_run!`, etc.) on `Object` so they're available as top-level console commands
+
+Each call to `claude` or `claude_run!` sends the full conversation history to the Claude API, maintaining context across turns. `claude_run!` additionally extracts fenced code blocks (`` ```ruby `` or `` ``` ``) from responses, evaluates them in the console context, and loops the result back for up to `max_iterations` rounds.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/lib/rails_claude/configuration.rb

@@ -0,0 +1,55 @@
+module RailsClaude
+  class Configuration
+    attr_accessor :api_key, :model, :max_tokens, :system_prompt, :safe_mode
+
+    def initialize
+      @api_key      = ENV["ANTHROPIC_API_KEY"]
+      @model        = "claude-opus-4-6"
+      @max_tokens   = 1024
+      @safe_mode    = defined?(Rails) ? Rails.env.production? : true
+      @system_prompt = nil # deferred until first access so safe_mode is settled
+    end
+
+    def system_prompt
+      @system_prompt || default_system_prompt
+    end
+
+    def safe_mode?
+      !!@safe_mode
+    end
+
+    private
+
+    def default_system_prompt
+      app_name = defined?(Rails) ? Rails.application.class.module_parent_name : "Rails"
+      models   = defined?(ApplicationRecord) ? ApplicationRecord.descendants.map(&:name).join(", ") : "unknown"
+
+      prompt = <<~PROMPT
+        You are a Rails developer assistant embedded inside a live Rails console for the #{app_name} app.
+
+        You help the user write ActiveRecord queries, debug issues, and explore the app.
+
+        Known models: #{models}
+        Rails environment: #{Rails.env}
+        Ruby version: #{RUBY_VERSION}
+        Rails version: #{Rails.version}
+
+        Keep responses concise and practical. When suggesting code, prefer single-line expressions
+        that work well in a REPL context. Remind the user if they need to run something manually.
+      PROMPT
+
+      if safe_mode?
+        prompt += <<~SAFE
+
+          IMPORTANT: Safe mode is ON. All executed code runs inside a read-only transaction
+          that is automatically rolled back. Only generate read-only code — SELECT queries,
+          inspections, and counts. Do NOT generate code that creates, updates, or deletes records,
+          runs migrations, modifies files, or executes system commands. Any database writes will
+          be rolled back and the user will be warned.
+        SAFE
+      end
+
+      prompt
+    end
+  end
+end

data/lib/rails_claude/railtie.rb

@@ -0,0 +1,28 @@
+module RailsClaude
+  class Railtie < Rails::Railtie
+    console do
+      Rails.application.eager_load!
+
+      session = RailsClaude::Session.new
+
+      Object.define_method(:claude)            { |msg|   session.ask(msg) }
+      Object.define_method(:claude_run!)       { |msg, **opts| session.ask_and_run(msg, **opts) }
+      Object.define_method(:claude_load_model) { |model| session.load_model(model) }
+      Object.define_method(:claude_load_file)  { |path|  session.load_file(path) }
+      Object.define_method(:claude_reset!)     { session.reset! }
+      Object.define_method(:claude_history)    { session.show_history }
+      Object.define_method(:claude_session)    { session }
+      Object.define_method(:claude_safe_mode!) { |enabled = true| session.set_safe_mode(enabled) }
+      Object.define_method(:claude_unsafe_mode!) { session.set_safe_mode(false) }
+
+      mode = RailsClaude.configuration.safe_mode? ? "\e[32m(safe mode)\e[0m" : "\e[33m(unrestricted)\e[0m"
+      puts "\e[35m✦ RailsClaude ready.\e[0m #{mode}"
+      puts "  \e[36mclaude\e[0m \"question\"           — chat"
+      puts "  \e[36mclaude_run!\e[0m \"question\"       — chat + auto-eval code"
+      puts "  \e[36mclaude_load_model\e[0m User         — load a model for analysis"
+      puts "  \e[36mclaude_load_file\e[0m \"path/to/f\" — load any file for analysis"
+      puts "  \e[36mclaude_safe_mode!\e[0m / \e[36mclaude_unsafe_mode!\e[0m"
+      puts "  \e[36mclaude_history\e[0m / \e[36mclaude_reset!\e[0m\n\n"
+    end
+  end
+end

data/lib/rails_claude/session.rb

@@ -0,0 +1,149 @@
+require "anthropic"
+
+module RailsClaude
+  class Session
+    attr_reader :history
+
+    def initialize
+      @config  = RailsClaude.configuration
+      @client  = Anthropic::Client.new(api_key: @config.api_key)
+      @history = []
+    end
+
+    def ask(message)
+      @history << { role: "user", content: message }
+
+      response = @client.messages.create(
+        model:      @config.model,
+        max_tokens: @config.max_tokens,
+        system:     @config.system_prompt,
+        messages:   @history
+      )
+
+      reply = response.content.first.text
+      @history << { role: "assistant", content: reply }
+      pretty_print(reply)
+      nil
+    end
+
+    def ask_and_run(message, max_iterations: 3)
+      @history << { role: "user", content: message }
+
+      max_iterations.times do
+        response = @client.messages.create(
+          model:      @config.model,
+          max_tokens: @config.max_tokens,
+          system:     @config.system_prompt,
+          messages:   @history
+        )
+
+        reply = response.content.first.text
+        @history << { role: "assistant", content: reply }
+        pretty_print(reply)
+
+        code = extract_code(reply)
+        break unless code
+
+        run_label = @config.safe_mode? ? "\e[33m🔒 Running (safe mode):\e[0m" : "\e[33m⚡ Running:\e[0m"
+        puts "#{run_label}\n#{code}\n"
+        result = safe_eval(code)
+        puts "\e[32m⮕ Result:\e[0m #{result}\n\n"
+
+        @history << { role: "user", content: "Result of running that code: #{result}" }
+      end
+
+      nil
+    end
+
+    def load_model(model)
+      klass = model.is_a?(Class) ? model : model.to_s.constantize
+      path  = source_path_for(klass)
+      raise "Could not find source file for #{klass}" unless path && File.exist?(path)
+      inject_file(path, label: "Model: #{klass}")
+    end
+
+    def load_file(path)
+      full_path = Rails.root.join(path)
+      raise "File not found: #{full_path}" unless File.exist?(full_path)
+      inject_file(full_path, label: path)
+    end
+
+    def set_safe_mode(enabled)
+      @config.safe_mode = enabled
+      if enabled
+        puts "\e[32m🔒 Safe mode enabled — code runs in rolled-back transactions.\e[0m"
+      else
+        puts "\e[33m⚠ Safe mode disabled — code will execute with full write access.\e[0m"
+      end
+      nil
+    end
+
+    def reset!
+      @history = []
+      puts "→ Conversation history cleared."
+      nil
+    end
+
+    def show_history
+      if @history.empty?
+        puts "No conversation history yet."
+      else
+        @history.each do |msg|
+          label = msg[:role] == "user" ? "\e[36mYou\e[0m" : "\e[35mClaude\e[0m"
+          puts "\n#{label}: #{msg[:content]}"
+        end
+      end
+      nil
+    end
+
+    private
+
+    def inject_file(path, label:)
+      content = File.read(path)
+      notice  = "I'm sharing this file for context — #{label}:\n\n```ruby\n#{content}\n```"
+      @history << { role: "user", content: notice }
+      puts "\e[36m→ Loaded #{label} into conversation context.\e[0m"
+      puts "  Ask Claude about it: claude \"explain this model\" or claude \"find N+1 issues\"\n\n"
+      nil
+    end
+
+    def extract_code(text)
+      text[/```ruby\n(.*?)```/m, 1] || text[/```\n(.*?)```/m, 1]
+    end
+
+    def safe_eval(code)
+      if @config.safe_mode?
+        safe_eval_readonly(code)
+      else
+        result = eval(code) # rubocop:disable Security/Eval
+        result.inspect
+      end
+    rescue StandardError => e
+      err = "#{e.class}: #{e.message}"
+      @history << { role: "user", content: "That code raised an error: #{err}" }
+      "\e[31mError — #{err}\e[0m"
+    end
+
+    def safe_eval_readonly(code)
+      output = nil
+      ActiveRecord::Base.transaction do
+        output = eval(code).inspect # rubocop:disable Security/Eval
+        raise ActiveRecord::Rollback
+      end
+      output
+    end
+
+    def source_path_for(klass)
+      m = klass.instance_methods(false).first
+      if m
+        file, = klass.instance_method(m).source_location
+        return file if file
+      end
+      Rails.root.join("app", "models", "#{klass.name.underscore}.rb").to_s
+    end
+
+    def pretty_print(text)
+      puts "\n\e[35mClaude:\e[0m #{text}\n\n"
+    end
+  end
+end

data/lib/rails_claude/version.rb

@@ -0,0 +1,3 @@
+module RailsClaude
+  VERSION = "0.1.0"
+end

data/lib/rails_claude.rb

@@ -0,0 +1,16 @@
+require "rails_claude/version"
+require "rails_claude/configuration"
+require "rails_claude/session"
+require "rails_claude/railtie" if defined?(Rails)
+
+module RailsClaude
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: rails_claude
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nick Pendery
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: anthropic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Provides an interactive Claude AI session directly in rails c, with Rails-aware
+  context.
+email:
+- npendery@homebot.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/rails_claude.rb
+- lib/rails_claude/configuration.rb
+- lib/rails_claude/railtie.rb
+- lib/rails_claude/session.rb
+- lib/rails_claude/version.rb
+homepage: https://github.com/npendery/rails-claude-console
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Chat with Claude inside your Rails console
+test_files: []