Assistant

A chat in the admin that works on the site for you: it finds, writes and changes content, orders and settings, and asks before every change.

kitloom/assistant · admins: kitloom/assistant-filament, kitloom/assistant-nova

Video lessons

Recorded in the Filament admin; the Nova admin works the same way.

The assistant

A chat in the admin that works on the site for you. Ask it in your own words — "find the pages without a meta description and write them one", "how many orders came in this week?", "move the old pricing page to the trash" — and it looks things up, proposes the changes and makes them once you approve. It acts with your rights: an editor's assistant edits what the editor may edit, nothing more.

The admin is kitloom/assistant-filament or kitloom/assistant-nova: the Assistant section with Chat, Settings and this page.

The assistant answers with the site's own AI model — the provider, key and monthly budget set up on AI Writer → Settings (kitloom/ai-writer) — and works with the same tools an AI agent gets over MCP (kitloom/ai): content, terms, media, settings, users, and every installed module's own (orders, bookings, redirects, SEO, menus, forms…). Connecting your own agent (Claude, Cursor) through MCP is still there for those who work in it; the assistant is for the rest of the team, inside the admin, with nothing to install.

Setting it up

1. Set up a model on AI Writer → Settings: a provider, its API key and a monthly budget. The chat page says so when none is set up, or when the month's budget is spent.
2. Give the Use the assistant permission (use_assistant) to the roles that should chat (Users → Roles). Administrators have it. Each answer may take a few questions of the model, paid with the site's key.
3. Press ✦ Assistant in the corner of any admin page, or open Assistant → Chat, and write.

On every page

The ✦ Assistant button in the bottom corner of every admin page opens the chat in a panel over the screen you are on. Each message carries the page with it — its title and address — so "shorten this excerpt", "translate this into French" or "why is this product out of stock?" mean the record you have open. The conversation goes on as you move from page to page (+ starts a new one, ↗ opens all your conversations on Assistant → Chat), and the panel stays open across a page load. In a demo sandbox the Feedback button sits beside it, and opening either panel closes the other.

While the conversation is empty the panel offers a few questions to start with, a click each. Only whoever may use the assistant sees the button. kitloom-assistant.widget set to false leaves the chat on its own page only.

How a change is made

• Reading runs at once: the assistant lists, opens and searches records as you would.
• Every tool that changes the site — create, update, trash, a setting, an order's status — waits for your approval. The chat shows what it is about to do and with which values (open the card to see them); Approve runs it, Reject tells the assistant no, and it asks what to do differently.
• Nothing is deleted for good: records go to the trash, from where they can be restored.
• What you may not do is refused as it is in the admin, and the assistant reads the refusal.
• Stop ends an answer that is taking too long.
• Unless the approvals are turned off (see Settings): then changes are made at once, and the chat says so above the conversation.

Settings

Assistant → Settings:

• Steps per answer — how many times the model may use a tool before it must answer (10 by default). Each step is a question the provider bills; a lower number keeps a confused answer cheap.
• Make changes without asking — off by default. Turned on, the assistant's changes are made the moment the model decides to, with the rights of whoever is chatting, and nobody approves each one. A model can misread a request, or be misled by a text it reads on the site (a comment, an imported page). Turning it on shows that warning and takes ticking I have read this and take full responsibility…; the acceptance is not stored, the switch is — and Activity Log, when installed, records who turned it on. Agents cannot change the assistant's settings (assistant_* is locked in kitloom-ai.settings.locked), so the model never turns its own approvals off.
• Keep conversations, days — conversations are deleted this long after their last message (90 by default); 0 keeps them for good.

What it costs

Every answer is one or more questions of AI Writer's model and counts in its Usage log under assistant.chat, with its tokens and cost, and against the same monthly budget as the translations and descriptions the other modules write. Once the budget is spent, the chat says so until the first of the month or until the budget is raised.

Two things keep a question small:

• Only the core tools are described to the model up front (content, terms, media, settings, users, pages — 21 of them). The modules' tools (94 on a site with the shop, bookings, courses and the rest) wait behind a tool search: the model looks up the one it needs — top_products for "which products sold best this month?" — and only that one's description is sent. Providers without tool search (Gemini, Mistral, …) get every tool, as before.
• The unchanging start of every question is cached: the tool descriptions and the instructions. Anthropic bills the cached part at a tenth of the input price or less (a twentieth for Sonnet and Opus); OpenAI caches a long prefix by itself. AI Writer's log counts the cached tokens at their own rate (cache_read, cache_write in kitloom-ai-writer.prices).

Measured on 2026-10-22 with Claude Haiku 5.5, the same three turns — a question that reads, a request to create a draft, its approval:

	Input tokens	Of them from the cache	Cost
Every tool described, no cache	165,358	—	$0.0168
Core tools + tool search, cached	36,612	22,389	$0.0022

About 4.5 times fewer input tokens and 7.8 times cheaper; one step of a turn went from about 43,000 input tokens to about 9,600.

Conversations and personal data

Each user sees only their own conversations, can open one to go on with it, and delete it. With kitloom/privacy, Tools → Export Personal Data includes the user's conversations (what they wrote and the answers; not the tools' results, which are the site's records), and Erase Personal Data deletes them. What they cost stays in AI Writer's log, which its own eraser takes the user off.

Where things are kept

What	Where
Conversations	tables agent_conversations and agent_conversation_messages (laravel/ai's, the site's table prefix in front)
Settings	options assistant_max_steps, assistant_auto_approve, assistant_keep_days
Configuration	config/kitloom-assistant.php

Configuration

config/kitloom-assistant.php of the package, merged into the application (php artisan vendor:publish --tag=kitloom-assistant-config).

Key	Default	What
path	kitloom-assistant	Where the chat's routes are: POST /{path}/chat, /{path}/conversations
max_steps	10	Steps per answer, while none is saved on the settings page
auto_approve	false	Changes without asking, while nothing is saved on the settings page
keep_days	90	Days to keep a conversation, while none is saved; 0 — for good
schedule	true	Whether assistant:prune runs daily on the scheduler
rate_limit	20	Messages a minute per user; 0 — no limit
widget	true	Whether the chat opens from a button on every admin page
widget_open (KITLOOM_ASSISTANT_OPEN)	false	Whether the panel opens by itself on a visit's first admin page — a demo's welcome; closed once, it stays closed for the visit
filament.register, nova.register	true	Whether the admin section is added
privacy.register	true	Whether the personal data export and erasure are tagged for kitloom/privacy

php artisan assistant:prune [--days=N] deletes old conversations by hand.

For developers

• The chat is laravel/ai's: Chat\AssistantAgent (instructions, tools, the stored conversation), streamed as the Vercel UI message stream (Http\ChatController). The browser sends only the new message, or the user's yes and no; what was said before is read from the database, never from the request.
• The tools are Kitloom\Ai\Mcp\KitloomServer::tools(), as the user would get them with a key that writes (Chat\Toolbox). A module's tool reaches the chat by being an AgentTool — nothing to add here. A tool that is not marked read-only (IsReadOnly, or writes(): false for an AgentTool) waits for approval, unless AssistantSettings::autoApprove().
• The model is asked through Kitloom\AiWriter\Writer::open(), which checks the key, the budget and the model's price and logs what the answer cost.
• The browser side is resources/js/assistant-chat.js, without dependencies: both admins' screens draw its state. resources/js/assistant-widget.js is the floating panel, the same in both admins, configured by Chat\WidgetConfig. The page goes with a message as page: {url, title}; the server puts it in front of the message as [Admin page: title — /path] (Chat\PageContext) — in the message, not the instructions, so the provider's cache holds — and the screens leave that line out.