The free, open source AI admin assistant for Magento 2 and Mage-OS.
Ask what sold best this week and get a live answer — or tell it to change a setting, and it does, after your OK.

askmago.com · Install · What you can ask · Build an addon

Running a Magento store means living in the admin panel: digging through reports, hunting for that one configuration setting, flushing the cache after every deploy. Mago puts a chat window in your admin and does that work with you.

Type a question in plain language and Mago answers with live data from your own store — revenue, best sellers, customers, configuration, content. Tell it to change something and it does it for you, but only after you've confirmed. It streams its answer as it works, shows numbers as stat cards, charts and tables where that helps, and never touches anything your admin role doesn't allow.

• Free, forever. Mago is open source under the MIT licence — no licence fee, no seats, no subscription. You only pay your AI provider for what you use, and Mago keeps its prompts small so a typical action costs a few cents.
• Your AI, your key. Bring your own Anthropic or OpenAI key (or Gemini, Azure, DeepSeek, Ollama and more). Requests go straight from your store to your provider — there is no Mago server in between.
• Nothing changes without your OK. Reading is instant; every write asks first. Irreversible actions such as cancelling an order or issuing a refund show their impact before you confirm.
• Follows your admin roles. Read and write access run through Magento's own ACL, so every admin sees exactly what their role allows.
• Answers you can act on. Stat cards, charts, tables and record lists, plus deep links straight into the admin page you need.
• Grows with the community. Agencies and module vendors add new skills as addons, without touching core.

See docs/skills-examples.md for more example prompts per skill.

• Natural language chat in the Magento admin panel
• Real-time streaming responses via SSE
• Built-in skills for sales analytics, store configuration, content management, and admin navigation
• Slash commands — /cache flush, /cache clean <type>, /index status, /index reindex run directly against Magento, no AI round-trip
• Extensible architecture — third-party modules can register custom skills via DI
• ACL-based permissions — read/write access controlled per admin role
• Write confirmation — every write asks first; irreversible actions (cancel, refund, delete) show their impact and need an explicit acknowledgement, several writes in one turn become a tick list
• Answer widgets — stat cards, charts, tables and record lists in the answer where the data allows it (see docs/ui-components.md)
• Write confirmation — destructive actions always require explicit user approval
• Form access — reads and stages field changes on the admin form open in the browser (including unsaved edits), but never saves: changes are only staged into the form's own fields, same as typing them in, and the administrator's own Save click is what persists anything
• Multi-provider — Anthropic, OpenAI, Azure, Google Gemini, DeepSeek, Hugging Face, OpenRouter, Ollama and LM Studio, through MageOS_AiBase
• Documentation grounding — answers admin how-to questions from Magento/Adobe Commerce docs, fetched into your database (optional)

• PHP >= 8.2
• Magento >= 2.4.9 or Mage-OS >= 3.0 (Symfony 7.3+ required by the AI bridges)
• An API key for one of the supported providers

Anthropic and OpenAI are included out of the box. For other providers (Azure, Gemini, DeepSeek, Ollama, LM Studio, etc.) install the matching Symfony AI bridge — see composer.json suggests.

composer require mago-assistant/mago
bin/magento module:enable MageOS_AiBase MagoAssistant_Mago
bin/magento setup:upgrade

First add a provider under Stores > Configuration > Mage-OS > AI Configuration: pick the backend, paste the API key, choose a model, and use Test Connection to check it answers.

Then, under Stores > Configuration > Mago Assistant:

1. Enable the module (General)
2. Pick the AI Service the assistant runs on (API Settings). Leave it on Automatic to use the first usable one, which is what a single-provider store wants.

If the module's internal REST API calls fail (e.g. in Docker environments where PHP can't reach itself via the public hostname), configure Stores > Configuration > Mago Assistant > API Settings > Internal API URL.

Examples:

• markshust/docker-magento: https://app:8443
• DDEV: https://ddev-<project>-web:443
• Leave empty to use the store's base URL (works for most setups)

These calls verify the TLS certificate by default. If the internal URL points at a host whose certificate cannot match (loopback addresses, container hostnames, self-signed certificates), set Verify TLS Certificate to No. Keep it enabled in production.

See docs/skills-examples.md for example prompts per skill and docs/skills-roadmap.md for the full roadmap of planned skills.

Typing / in the chat shows the available commands. These run without the AI provider and reply instantly:

Write commands need the MagoAssistant_Mago::assistant_write ACL resource plus a write grant on the underlying skill. See docs/skills-architecture.md for registering your own commands.

The answer widgets and skill cards the chat panel renders are documented in docs/ui-components.md; docs/ui-components-examples.md shows every component with sample data and the call behind it. page_form reads the admin form currently open in the browser and can stage new field values for the administrator to confirm — it never writes to the database itself, only into the same fields the administrator would type into, so their own Save button is what persists anything. See docs/form-access.md for what it can see, which forms are excluded, and the directive contract it uses to reach the browser.

When enabled, the assistant can answer "how do I…" questions from the official Magento admin documentation instead of guessing. The docs_search skill runs a MySQL FULLTEXT search over an indexed copy of the docs and cites the source page it used.

Stores > Configuration > Mago Assistant > Documentation

A cron job (mago_docs group, its own process) indexes the docs into the mago_doc table (~5 MB). To index immediately instead of waiting for the cron:

bin/magento mago:docs:index --force

Sync is cheap to run often because it is change-detected by git tree SHA: an unchanged source repo costs a single API call and skips re-fetching entirely. This is why the default schedule can safely be raised when you feed docs that update more often than the Mage-OS mirror. On a real change, every help/**.md is fetched (including _includes/, needed to resolve {{$include}} partials), Experience League markup is normalized to plain text, and the table is swapped in a single transaction — a failed sync keeps the previous corpus, and searches keep answering from the old corpus until the new one is committed. Only one sync runs at a time: a second invocation (cron overlapping a manual run, or a double-started command) reports another sync is already running and exits instead of interfering.

Retrieval uses a MySQL FULLTEXT index rather than vector embeddings so the feature works on any Magento install with zero extra infrastructure — no vector database, no embeddings service, and no dependency on a specific AI provider (Anthropic, for one, has no embeddings API). For a bounded, well-structured doc corpus this keyword search is accurate enough, and the assistant compensates for the lack of semantic matching by issuing multiple searches with different terms when the first result set is thin. Semantic/vector retrieval can be added later as an optional backend without changing the skill contract.

The pipeline is source-repo agnostic: point Source repository at any public GitHub repo of Adobe Experience League-flavored (or plain) markdown to ground the assistant on your own documentation. Private repos and non-GitHub sources are on the roadmap.

Third-party modules can register tools by implementing ToolInterface and adding them to the ToolRegistry via di.xml. No core modifications needed.

See docs/skills-architecture.md for the full architecture reference, including:

• How the skill/tool system works
• Step-by-step guide for building custom skills
• ACL and permissions model
• Data & privacy details
• MCP compatibility roadmap

End-to-end tests run with Playwright against Chromium. No test calls a real provider: the chat panel is covered with browser-level SSE stubs, the backend with WireMock standing in for the provider endpoint.

cd Test/End-2-end
npm install && npx playwright install chromium
BASE_URL="https://your-store.test/" npx playwright test

See Test/End-2-end/README.md for configuration, the WireMock setup and how to add scenarios.

Mago stores nothing outside your Magento installation. Every request goes directly from your store to the AI provider you configured, using your own API key; what that provider does with the request is governed by its API terms. Mago only reads what the current admin's role allows and never writes without an explicit confirmation. Details in docs/skills-architecture.md.

Mago is built in the open with developers, community builders and backers from the Dutch Magento ecosystem. Issues and pull requests are welcome at github.com/mago-assistant; brand assets and press material live at askmago.com/brand.html.

MIT