AI Chat

The AI chat is the centerpiece of Contentrain Studio. It is a Claude-powered conversation interface that lets you manage content, models, and project configuration through natural language. Every action the agent takes creates a real Git commit — auditable, reviewable, and reversible.

Studio chat should be understood as the web continuation of the same package contract described in Contentrain AI. @contentrain/rules and @contentrain/skills define the quality and workflow expectations; Studio turns those expectations into an authenticated team interface with roles, review, and delivery.

Chat Panel Overview

The chat panel occupies the center of the three-panel project workspace. It consists of:

• Conversation area: Scrollable message history with user and assistant messages
• Tool call indicators: Expandable cards showing what the agent did
• Context bar: Pinned items from the content panel (above the input)
• Input area: Message input with model selector, an attach button, and a send button (a Stop button replaces it while the agent is responding)
• Conversation history: A list of past conversations that opens from the Chat title in the panel header

Sending Messages

Type your message in the input area and press Enter (or click the send button). The agent processes your message and responds with:

1. Text response — explanation, confirmation, or follow-up question
2. Tool calls — actions performed on your content (shown as expandable cards)
3. Affected resources — what changed as a result of the conversation

Messages stream in real-time via Server-Sent Events (SSE). You can see the response building character by character.

Example Prompts

Here are common tasks you can accomplish through chat:

Content Management:

"Create a blog post titled 'Getting Started with Studio' with a summary
and set the published date to today"

"Update the homepage hero tagline to 'Build content, not infrastructure'"

"Delete all FAQ entries that have 'deprecated' in the title"

"Show me all team members and their roles"

Model Management:

"Create a collection model called 'Testimonials' in the marketing domain
with author (string), quote (text), rating (rating), and avatar (image)"

"Add a 'featured' boolean field to the Blog Posts model"

"List all models and their field counts"

Branch Management:

"List all pending content branches"

"Merge the branch cr/content/blog-posts/en/..."

"Show me what changed in the latest branch"

Localization:

"Copy all English blog posts to Turkish"

"Add the key 'nav.products' with value 'Products' to the UI Strings
dictionary in English"

Media:

"Upload this image from https://example.com/hero.jpg as the hero banner
with alt text 'Product dashboard screenshot'"

"Search the media library for images tagged 'team'"

Media uploads need CDN delivery

Uploading an image into the media library (a media-intent upload) requires the project's CDN delivery to be enabled. If it is off, the agent returns an actionable error rather than storing a broken asset — attach the file as context (see Context Chips) so the agent can still read it inline. See CDN to turn delivery on.

Model Selection

Studio offers three Claude AI models with different performance profiles:

Model	Label	Best For
claude-haiku-5-5	Haiku 5.5	Fast & economic: simple queries, quick lookups
claude-sonnet-5-5	Sonnet 5.5	Balanced, newest generation: the default where available
claude-opus-5-5	Opus 5.5	Most capable: complex, multi-step operations, nuanced content

Which models you can pick depends on the plan's Advanced AI Models feature (ai.pro_models):

Plan	Models Available
Starter	Haiku 5.5
Pro	Haiku 5.5, Sonnet 5.5, Opus 5.5
Enterprise	Haiku 5.5, Sonnet 5.5, Opus 5.5
Community (self-host)	Haiku 5.5, Sonnet 5.5, Opus 5.5 (on your own key)

Sonnet 5.5 is selected by default on plans that include it; on Starter the agent uses Haiku 5.5. A request for a model the plan does not grant falls back to the default. A saved choice or API key that names a retired model ID (for example claude-sonnet-5 or claude-haiku-4-5-20251001) runs on the current model of the same family. During a trial on the Studio-hosted key, Opus 5.5 is not available; with your own key (BYOA) or a paid subscription it is. The selector sits next to the input area.

TIP

Haiku is ideal for quick queries like "list all models" or "show me the site settings." Save Opus for complex, multi-step tasks like "create a blog structure with three related models and sample content."

Tool Calls Explained

When the agent performs an action, it uses tools — specialized functions that interact with your project. Tool calls appear as expandable cards in the conversation.

Expand a tool card to inspect its result — for example, save_content returns the branch, commit SHA, files changed, validation, and merge status:

Available Tools

Tool	Purpose	Creates Branch?
list_models	List all models with field schemas, kind, domain, i18n	No
get_content	Read content entries for a model and locale	No
save_content	Create or update content (merges changed fields)	Yes
replace_in_field	Find and replace text inside a text field without re-sending the whole field	Yes
delete_content	Remove entries or dictionary keys	Yes
save_model	Create or update a model definition	Yes
validate	Validate content against schemas	No
list_branches	List pending content branches	No
merge_branch	Merge a branch into the contentrain branch	Yes (merge commit)
reject_branch	Reject and delete a branch	Yes (branch deletion)
request_changes	Send a pending branch back to its author with a comment; the branch stays open	No
init_project	Initialize .contentrain/ structure	Yes
copy_locale	Copy content between locales	Yes
brain_query	Read content from cache (fast)	No
brain_search	Full-text search across content	No
search_media	Search the media library	No
upload_media	Upload an image from URL	No
get_media	Get asset metadata	No
update_status	Publish, unpublish, or archive entries	Yes
update_media	Update asset alt text, tags, or focal point	No
delete_media	Delete an asset and all its variants	No
branch_health	Check pending-branch health vs warn/block limits	No
relation_expand	Resolve forward/reverse relations for an entry	No
vocabulary	Read or update the project glossary	Yes
add_locale	Register a new supported locale in the config	Yes
delete_model	Permanently delete a model and all its content	Yes
brain_analyze	Analyze content (SEO, locale parity, stale, quality)	No
validate_schema	Comprehensive schema validation with health score	No
list_submissions	List form submissions for a model	No
approve_submission	Approve a submission (creates a content entry)	Yes
reject_submission	Reject a form submission	No
list_comments	List comments by status (default: pending), optionally for one model or entry	No
approve_comment	Approve a comment so it is shown publicly	No
reject_comment	Reject a comment or mark it as spam	No
reply_comment	Post a public moderator reply; replying to a pending comment approves it first	No

Tool Call Lifecycle

Each tool call goes through these states:

1. Pending — Tool is about to execute
2. Streaming — Tool is running (for long operations)
3. Complete — Tool finished successfully, result is shown
4. Error — Tool execution failed, error message is shown

Click on a tool call card to expand it and see the input parameters and result.

Workflow Behavior

Tools that modify content follow one of three workflows:

Behavior	Description
Auto-merge	Changes merge automatically to the contentrain branch (used for init)
Workflow-dependent	Follows the project's merge workflow setting. On a review project the write may wait on its branch for approval; see Approval Policy
Manual	Requires explicit user action (merge/reject branch tools)
None	Read-only tools, no Git changes

Context Chips

Context chips let you give the agent focused awareness of what you are working on. Instead of describing your context in text, you can pin items from the content panel.

Pinning Context

There are two ways to pin context:

1. Click the pin icon — Hover over a model, entry, or field in the content panel and click the pin icon
2. Drag and drop — Drag an item from the content panel to the context bar above the chat input

Context Types

Type	What It Provides
Model	Full model schema with fields, kind, and domain
Entry	Specific entry data with all field values
Field	Individual field value and metadata
Asset	Media asset information from the library

How Context Helps

When you pin a model and ask "add a new entry," the agent knows exactly which model you mean and what fields are available. Without context, you would need to specify the model name in your message.

Without context:

"Create a new entry in the Blog Posts model with title 'Hello World'"

With Blog Posts model pinned:

"Create a new entry with title 'Hello World'"

Context chips appear as removable tags above the input. Click the X on any chip to remove it.

Attaching Files and Links

Click the attach button next to the input, drop files onto the chat panel, or paste a link. Each attachment goes to one of two places:

Destination	What happens
Attach as context	The agent reads the file or link. It is not stored. Large content may be truncated to fit
Upload to media library	The file is stored as a reusable media asset (needs CDN delivery, see the note above)

If a turn fails, the error banner offers Retry to run it again.

Conversation History

Studio preserves your conversation history per project. You can:

• Browse past conversations — Click the Chat title in the panel header to open the list, with auto-generated titles
• Load a conversation — Click to restore the full message history
• Delete a conversation — Remove conversations you no longer need
• Start a new conversation — Click the "New conversation" button or use the command palette

TIP

Conversation titles are auto-generated from the first message. They help you find past conversations quickly.

BYOA (Bring Your Own API Key)

By default, Studio uses its own API key with a monthly AI credit allowance based on your plan. With BYOA, you can add your own Anthropic API key for unlimited usage.

Adding Your Key

1. Navigate to Workspace Settings > AI (the key is personal: only you see it)
2. Paste your Anthropic API key into the key field
3. Click Add API Key

Your key is encrypted at rest and visible only to you. It is used only for your own chat requests in this workspace; each member adds their own.

WARNING

BYOA is a paid feature, available on Pro and above. The Free plan uses only the studio-provided key and has 0 AI credits per month.

Plan Limits

Plan	AI credits/month	BYOA
Free	0	Not available
Community (self-host)	Unlimited	Not available
Starter	300	Not available
Pro	1,600	Available
Enterprise	Unlimited	Available

AI usage on the Studio-hosted key is counted in AI credits. One credit stands for $0.01 of model spend: a light message uses 1 credit, and a heavier turn (long context, many tool calls, a larger model) uses credits in proportion to what it actually cost. One message can use at most 75 credits on Starter and 150 on other plans. Subscriptions started before the current credit catalogue keep the credits and prices they were sold with.

When using BYOA, your messages do not count toward credits and are not billed by Studio — you are billed directly by Anthropic for API usage.

Bounded Task Executor

The AI agent operates within a bounded task executor — a controlled environment with strict guardrails:

What the Agent Can Do

• Create, modify, and delete content models
• Add, update, and remove content entries (all four model kinds)
• Change publish status (publish, unpublish, archive)
• Manage vocabulary terms and register new locales
• Copy content between locales
• Search, upload, update, and delete media assets
• Initialize project structure
• List and manage branches, and check branch health
• Validate content and run schema/content health analysis
• Review form submissions (approve or reject)

What the Agent Cannot Do

• Access repositories outside the current project
• Bypass role-based permissions (the agent respects your role)
• Push directly to the main branch (every change goes through a cr/* branch first)
• Access external services or browse the internet
• Execute arbitrary code or shell commands
• Modify Git history or rebase branches

Safety Guarantees

• Every mutation creates a branch — Changes go to cr/* branches and reach main only through a merge
• Auditable — Every tool call is logged in the conversation and visible in branch diffs
• Reversible — Reject a branch to discard all changes
• Permission-scoped — The agent checks your role before executing tools
• Iteration-limited — Maximum 8 tool iterations per message to prevent runaway loops; at the limit the agent stops calling tools and summarises what it did
• Context-limited — Tool results are truncated to manage the AI context window

Error Handling

If a tool call fails, the agent will:

1. Show the error in the tool call card
2. Explain what went wrong in its text response
3. Suggest corrective action if possible

Common error scenarios:

• Validation failure — Content does not match the model schema
• Branch conflict — Another operation modified the same file
• Permission denied — Your role does not allow the requested action
• Rate limit exceeded — You have used your plan's AI credits for the month

Streaming Architecture

The chat endpoint uses Server-Sent Events (SSE) for real-time streaming:

1. Your message is sent as a POST request
2. The server opens an SSE stream
3. Events are emitted as they occur:
   • conversation — Conversation ID assigned
   • text — Response text chunk
   • tool_use — Tool call started
   • tool_input — The tool call's input is complete
   • tool_result — Tool call completed
   • done — Conversation turn complete, affected resources reported
   • error — Error occurred during processing

This architecture provides a responsive experience — you see the agent's response building in real-time and can observe tool execution as it happens.

Next Steps

• Content Models — Understand the models the agent works with
• Content Editing — Use the content panel alongside the chat
• Branches & Review — Review changes the agent creates
• Keyboard Shortcuts — Navigate quickly with the command palette