Skip to main content

Catalyst AI

Catalyst AI (CT Bot) is an opt-in chat assistant inside the admin panel. It answers questions with MCP tools on your models, streams replies, asks clarifying questions and asks for confirmation before changing data. What you get:

  • Floating chat widget on every admin page β€” history, unread badges, file attachments, Lexxy composer
  • Streaming replies over ActionCable
  • Clarifying questions β€” the assistant asks before guessing, on a card the user answers
  • Confirmed writes β€” tools that change data never run until the user confirms
  • Per-role opt-in β€” the is_catalyst_ai_enabled flag on CmRole
  • Cost tracking β€” every LLM call recorded with tokens, cost and raw payload
  • Permission-scoped answers β€” the same Pundit scopes as the web UI, for the asking user

Quick example​

rails generate cm_admin:add_bot_conversations
rails generate cm_admin:add_bot_transcriptions
rails db:migrate
rails credentials:edit
catalyst_ai:
openrouter_api_key: sk-or-...

Then register the models, declare mcp_actions on the models it may query and enable Catalyst AI on a role. See Setup.

Setup​

1. Generate and run the migrations​

rails generate cm_admin:add_bot_conversations
rails generate cm_admin:add_bot_transcriptions
rails db:migrate

add_bot_conversations creates ct_bot_conversations, ct_bot_messages, ct_bot_artifacts, the ruby_llm_* persistence tables (ruby_llm_models, ruby_llm_tool_calls, ruby_llm_usages, ruby_llm_queued_messages, ruby_llm_mcp_credentials, ruby_llm_chat_files, ruby_llm_batches, ruby_llm_provider_files), and adds is_catalyst_ai_enabled to cm_roles. add_bot_transcriptions (added in v8.4.1) creates ct_bot_transcriptions for voice input. See the generator reference for Add Bot Conversations and Add Bot Transcriptions.

Already running Catalyst AI from an earlier version? Don't rerun add_bot_conversations β€” run rails generate cm_admin:add_ruby_llm_persistence && rails db:migrate instead. It adds the same ruby_llm_* tables, converts ct_bot_messages.role to a string, backfills the default bot model and links existing conversations to it, and renames message attachments from files to attachments β€” update any app code that used the files param or association accordingly. See Add Ruby LLM Persistence.

2. Register the models​

# config/initializers/zcm_admin.rb
config.included_models = [..., CtBotConversation, CtBotMessage, CtBotTranscription, RubyLlmUsage]

3. Add your OpenRouter API key​

rails credentials:edit
catalyst_ai:
openrouter_api_key: sk-or-...

4. Configure ActionCable​

Replies stream over CmAdmin::CtBotChannel. Make sure config/cable.yml exists β€” Redis is recommended outside development:

production:
adapter: redis
url: <%= ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" } %>

5. Enable the assistant on roles​

Edit each CmRole in the admin panel and switch on Catalyst AI. The widget renders only for users whose role has the flag β€” and the chat endpoints return 404 without it.

6. Expose models to the assistant​

The assistant can only query models that declare mcp_actions (same mechanism as the external MCP Server):

class Article < ApplicationRecord
cm_admin do
mcp_actions
end
end

Models without mcp_actions are invisible to the assistant.

7. (Optional) Give the assistant domain context​

config.mcp_system_prompt doubles as the bot's system prompt β€” set it to explain your data model and business semantics:

# config/initializers/zcm_admin.rb
CmAdmin.configure do |config|
config.mcp_system_prompt = <<~PROMPT
You are the Acme Platform admin assistant.
- `assignee` is the current owner of a work item.
- Prefer aggregate tools for counts and totals.
PROMPT
end

How it works​

  1. The widget renders in layouts/cm_admin when Current.user.cm_role.catalyst_ai_enabled?. It opens on the user's most recent conversation (or a fresh one) inside a lazy turbo frame.

  2. Sending a message creates a CtBotMessage (role: :user), which triggers request_reply: open artifacts are closed and CtBotReplyJob is enqueued for the conversation. If the conversation still has a live run claim (running?, backed by claim_token/claimed_until), the job retries after CtBotReplyJob::RUN_WAIT (15s) instead of starting a second run β€” the new message is included when the reply continues. Input queued while a run is in flight lives in ruby_llm_queued_messages; the agent's around_join hook joins those records as normal success/read user messages.

  3. The job hands the conversation to CmAdmin::CtBotReplyService. CtBotAgent.find(conversation.id) returns the acts_as_chat record with the agent's configuration applied β€” a ruby_llm agent connected in-process to CmAdmin::Mcp::Server β€” so message history, pending tool calls and usage are read from the ct_bot_*/ruby_llm_* tables rather than replayed by hand. Current.user is set to the conversation owner, so every MCP tool call is scoped by CmAdmin::<Model>PolicyIndexScope for that user. Leftover pending questions (e.g. a confirmation card the user never answered) are declined, then chat.complete continues the run.

  4. Streamed chunks carry the persisted assistant record (chunk.message); its markdown is rendered and broadcast over the signed CmAdmin::CtBotChannel stream (throttled to ~4/second), and the message partial re-renders live until the reply finishes. role is a string enum β€” the widget lists only CtBotMessage.visible rows (user and assistant); internal system and tool messages appear only in the admin indexes, with their own badge colors.

  5. If the agent calls ask_user_question, the pending tool call is mirrored on a question CtBotArtifact (its tool_call_id points at the ruby_llm_tool_calls row). The tool takes a questions array so related questions are asked together; each question's type must be one of CtBotArtifact::QUESTION_TYPES:

    • single_select β€” radio options plus an Other text box (one answer)
    • multi_select β€” checkbox options plus an optional Other text box
    • text β€” a text box only, for open-ended answers

    Each question also carries an is_required flag. Required questions must be answered before submitting; optional ones can be skipped and post as Skipped in the summary.

    A single question renders as one card. Several questions render as a stepped card β€” a progress bar, Back / Next, and Submit answers on the last step; Next (or Enter in a text box β€” Shift+Enter adds a new line) moves to the next step. Every required question must be answered before submitting. Submitting settles the stored ask_user_question tool call β€” CtBotArtifact#settle_tool_calls approves it on the rehydrated chat so the answers become its tool result β€” and posts the answers together as one user message (Question β€” answer per line when there is more than one question), which triggers a fresh reply.

  6. CtBotMcp marks every MCP tool that is not read-only (readOnlyHint: false, such as create tools) with requires_approval. When the agent calls one, the run pauses: the calls (name, arguments, id) persist as ruby_llm_tool_calls rows and are mirrored on a confirmation CtBotArtifact, rendered as a card listing the fields with Confirm / Cancel buttons. decide! settles them via settle_tool_calls β€” each stored call is approved or declined on the chat and chat.run_tools executes or rejects it immediately, so a confirmed create happens on click with exactly the arguments the user reviewed. The decision also posts a "Confirmed" / "Cancelled" user message, which triggers the reply that summarizes the outcome. Sending a free-text message instead closes the card and the calls are declined (recorded denied) when the next reply begins β€” the assistant is told the user changed their mind and can ask what to change.

  7. ruby_llm records each provider call in ruby_llm_usages, linked to the reply message; the service attaches the raw request payload to each usage created since the reply began. Each usage refreshes the message's total_cost (sum of its usages), which in turn refreshes the conversation's total_cost β€” visible per message and in the LLM Usages index.

  8. On failure the reply is marked failed with a friendly error message and the exception is reported through CmAdmin.report_error (Rails.error with source: "cm_admin" β€” Airbrake and friends still work via their error subscribers).

  9. Voice input uploads the recording as a CtBotTranscription (audio attached, linked to the open conversation if any) and enqueues CtBotTranscriptionJob. The job stores the transcribed text and status; each provider attempt is attributed to the transcription in ruby_llm_usages (via owner:), then the result is broadcast over the signed CmAdmin::CtBotTranscriptionChannel stream. When a message is sent in that conversation, the transcription is linked to the CtBotMessage.

Platform settings​

Four admin-managed settings under the Catalyst AI category configure runtime behavior (create them via CmPlatformSetting.add_cm_default_settings or the Platform Settings page):

SettingSlugPurposeDefault
CT Bot Greetingct-bot-greetingMessage shown at the start of every new chatHi! How can I help you today?
CT Bot Modelct-bot-modelOpenRouter model ID (e.g. openai/gpt-5.6)openai/gpt-5.6-sol
CT Bot Queuect-bot-queueSidekiq queue used for CtBotReplyJob and CtBotTranscriptionJobdefault
CT Bot Transcription Modelct-bot-transcription-modelOpenRouter model ID used to transcribe voice inputopenai/gpt-transcribe

Admin views​

  • Bot Conversations β€” index + show (with a Messages tab) for auditing chats, including a rolled-up Total Cost column
  • Bot Messages β€” index/show per message with Total Cost, including a Cost Trackings tab; internal system/tool messages show here with their own badge colors even though the widget hides them
  • Bot Transcriptions β€” index/show per voice recording with its audio, text, status and Total Cost, including a Cost Trackings tab
  • Cost Trackings β€” global index with provider/model filters

Permission rows for CtBotConversation/CtBotMessage appear on a role only while Catalyst AI is enabled; disabling the flag removes them.

Security notes​

  • All chat endpoints require a Catalyst-AI-enabled role and scope every query to Current.user β€” users can only read their own conversations.
  • Channel subscriptions use signed stream names; a stream for another user's conversation can't be forged.
  • Attachment previews are served inline only for non-SVG images; everything else downloads as an attachment.
  • The bot's data access goes through the same Pundit policies and scopes as the web UI β€” it cannot see or create records the asking user couldn't. Reads run freely; any write needs the user's explicit confirmation first.