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_enabledflag onCmRole - 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
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β
-
The widget renders in
layouts/cm_adminwhenCurrent.user.cm_role.catalyst_ai_enabled?. It opens on the user's most recent conversation (or a fresh one) inside a lazy turbo frame. -
Sending a message creates a
CtBotMessage(role: :user), which triggersrequest_reply: open artifacts are closed andCtBotReplyJobis enqueued for the conversation. If the conversation still has a live run claim (running?, backed byclaim_token/claimed_until), the job retries afterCtBotReplyJob::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 inruby_llm_queued_messages; the agent'saround_joinhook joins those records as normalsuccess/readuser messages. -
The job hands the conversation to
CmAdmin::CtBotReplyService.CtBotAgent.find(conversation.id)returns theacts_as_chatrecord with the agent's configuration applied β aruby_llmagent connected in-process toCmAdmin::Mcp::Serverβ so message history, pending tool calls and usage are read from thect_bot_*/ruby_llm_*tables rather than replayed by hand.Current.useris set to the conversation owner, so every MCP tool call is scoped byCmAdmin::<Model>PolicyIndexScopefor that user. Leftover pending questions (e.g. a confirmation card the user never answered) are declined, thenchat.completecontinues the run. -
Streamed chunks carry the persisted assistant record (
chunk.message); its markdown is rendered and broadcast over the signedCmAdmin::CtBotChannelstream (throttled to ~4/second), and the message partial re-renders live until the reply finishes.roleis a string enum β the widget lists onlyCtBotMessage.visiblerows (userandassistant); internalsystemandtoolmessages appear only in the admin indexes, with their own badge colors. -
If the agent calls
ask_user_question, the pending tool call is mirrored on aquestionCtBotArtifact(itstool_call_idpoints at theruby_llm_tool_callsrow). The tool takes aquestionsarray so related questions are asked together; each question'stypemust be one ofCtBotArtifact::QUESTION_TYPES:single_selectβ radio options plus an Other text box (one answer)multi_selectβ checkbox options plus an optional Other text boxtextβ a text box only, for open-ended answers
Each question also carries an
is_requiredflag. Required questions must be answered before submitting; optional ones can be skipped and post asSkippedin 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_questiontool call βCtBotArtifact#settle_tool_callsapproves it on the rehydrated chat so the answers become its tool result β and posts the answers together as one user message (Question β answerper line when there is more than one question), which triggers a fresh reply. -
CtBotMcpmarks every MCP tool that is not read-only (readOnlyHint: false, such as create tools) withrequires_approval. When the agent calls one, the run pauses: the calls (name, arguments, id) persist asruby_llm_tool_callsrows and are mirrored on aconfirmationCtBotArtifact, rendered as a card listing the fields with Confirm / Cancel buttons.decide!settles them viasettle_tool_callsβ each stored call is approved or declined on the chat andchat.run_toolsexecutes 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 (recordeddenied) when the next reply begins β the assistant is told the user changed their mind and can ask what to change. -
ruby_llmrecords each provider call inruby_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'stotal_cost(sum of its usages), which in turn refreshes the conversation'stotal_costβ visible per message and in the LLM Usages index. -
On failure the reply is marked
failedwith a friendly error message and the exception is reported throughCmAdmin.report_error(Rails.errorwithsource: "cm_admin"β Airbrake and friends still work via their error subscribers). -
Voice input uploads the recording as a
CtBotTranscription(audio attached, linked to the open conversation if any) and enqueuesCtBotTranscriptionJob. The job stores the transcribed text and status; each provider attempt is attributed to the transcription inruby_llm_usages(viaowner:), then the result is broadcast over the signedCmAdmin::CtBotTranscriptionChannelstream. When a message is sent in that conversation, the transcription is linked to theCtBotMessage.
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):
| Setting | Slug | Purpose | Default |
|---|---|---|---|
| CT Bot Greeting | ct-bot-greeting | Message shown at the start of every new chat | Hi! How can I help you today? |
| CT Bot Model | ct-bot-model | OpenRouter model ID (e.g. openai/gpt-5.6) | openai/gpt-5.6-sol |
| CT Bot Queue | ct-bot-queue | Sidekiq queue used for CtBotReplyJob and CtBotTranscriptionJob | default |
| CT Bot Transcription Model | ct-bot-transcription-model | OpenRouter model ID used to transcribe voice input | openai/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/toolmessages 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.