konradmichalik / typo3-ai-mate

0.5.0 2026-08-31 09:40 UTC

Requires

• php: ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0
• ext-mbstring: *
• doctrine/dbal: ^4
• helgesverre/toon: ^3.2.1
• konradmichalik/typo3-request-profiler: ^0.5 || ^0.6
• nikic/php-parser: ^5.8.0
• psr/http-server-handler: ^1.0.2
• psr/http-server-middleware: ^1.0.2
• psr/log: ^3.0.2
• symfony/ai-mate: ^0.13
• symfony/console: ^6.4 || ^7.0 || ^8.0
• symfony/dependency-injection: ^6.4 || ^7.0 || ^8.0
• symfony/finder: ^6.4 || ^7.0 || ^8.0
• symfony/process: ^6.4 || ^7.0 || ^8.0
• symfony/routing: ^6.4 || ^7.0 || ^8.0
• typo3/cms-backend: ^13.4 || ^14.3
• typo3/cms-core: ^13.4 || ^14.3
• typo3/cms-fluid: ^13.4 || ^14.3
• typo3/cms-install: ^13.4 || ^14.3

Requires (Dev)

• composer/class-map-generator: ^1.7.3
• eliashaeussler/version-bumper: ^4.1.0
• konradmichalik/ttt: ^0.4.0
• phpunit/phpcov: ^9.0 || ^10.0 || ^11.0 || ^13.0
• phpunit/phpunit: ^10.5 || ^11.0 || ^12.0 || ^13.0
• psr/http-message: ^1.0 || ^2.0
• symfony/yaml: ^6.4 || ^7.0 || ^8.0
• typo3/cms-base-distribution: ^13.4 || ^14.3
• typo3/testing-framework: ^9.6.1

GPL-2.0-or-later

• Konrad Michalik

Published on Packagist.org on 2026-08-31 09:49 UTC

README

TYPO3 extension typo3_ai_mate

AI assistants normally read your raw source and config files and guess at the result. But the state that actually matters, the merged TCA, the resolved TypoScript of a page, the real PSR-15 middleware order, whether a request was cached, is computed at runtime and cannot be reliably inferred from files alone.

This dev-only extension hands the assistant that already-resolved state instead, through symfony/ai-mate's mate CLI. It is usually cheaper too: a compact resolved summary costs far fewer tokens than having the assistant read and reason over the raw sources.

Warning

This package is in early development stage and may change significantly in the future. I am working steadily to release a stable version as soon as possible.

Important

This package is active only in a Development context (Environment::getContext()->isDevelopment()).

✨ Features

• 32 read-only diagnostic tools over the resolved runtime state: TCA, page composition, records, TypoScript, TSconfig, Fluid resolution, PSR-15 and PSR-14 chains, logs, per-request profiles and more. See the tool reference.
• Answers, not empty structures. A miss reports registered: false or unsupported with a reason, so an assistant stops instead of retrying with different arguments.
• Prompt-injection aware. Output captured from the installation arrives wrapped as untrusted data, never as instructions.
• Diagnose without booting TYPO3 twice. The tools shell out to the installation's own console, so they report what it actually computed. See how it works.
• Upgrade support: static breaking-change scan, outstanding wizards, runtime deprecations with own-code origins, and offline changelog search. See use cases.

🔥 Installation

Requirements

• TYPO3 13.4 LTS & 14.3 LTS
• PHP 8.2+
• Composer mode

Composer

composer require --dev konradmichalik/typo3-ai-mate

Note

Requiring typo3-ai-mate automatically pulls in symfony/ai-mate (the mate CLI) and konradmichalik/typo3-request-profiler (the profile source for the typo3-profiler-* tools). No separate installs needed.

TER

Download the zip file from TYPO3 extension repository (TER).

🚀 Quick start

One command scaffolds the Mate workspace and materializes the agent instructions:

vendor/bin/typo3 typo3-ai-mate:install

That is all it does: it runs mate init and mate discover. Re-run it after every composer update so changed tool descriptions reach mate/AGENT_INSTRUCTIONS.md, then reload your assistant.

There is no server process to connect to. Your assistant calls the tools by running vendor/bin/mate tools:call <name> --<param>=<value> as a shell command, guided by a managed CLAUDE.md/AGENTS.md block that mate init writes. An assistant that reads only its own file, such as .cursor/rules, needs that import added by hand.

See connecting an assistant for what exactly gets written, the Agent Skills that come along, and what to clean up when upgrading from 0.4 or earlier.

📖 How it works

The typo3-* tools run in the Mate process, invoked per call by vendor/bin/mate tools:call. They boot no TYPO3: they reach it by shelling out to vendor/bin/typo3 <command> and reading its JSON, or by reading profile artifacts directly.

flowchart LR
    A["AI agent (e.g. Claude)"] -->|"vendor/bin/mate tools:call"| B["Mate process (typo3-* tools)"]
    B -->|shell out| C["TYPO3 process (vendor/bin/typo3)"]
    C -->|JSON| B

Loading

Details, including why tool descriptions cannot carry runtime state, are in how it works.

📚 Documentation

Page	What is inside
Tool reference	Every tool, what it answers, and which clusters can come back empty
Connecting an assistant	What mate init/discover write, Agent Skills, upgrading from 0.4
How it works	The two-process architecture and why descriptions are static
Security	Trust boundary, guards, and the untrusted-data envelope
Use cases	Slow page, error page, major upgrade, and the request_id anchor
Extending	Writing your own typo3-* tool against Typo3CliRunner
Tool surface	What the tool count costs a session, measured rather than argued
Related projects	How this compares to dev-companion and the two typo3-mcp-server projects

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md. Changes worth knowing about are recorded in CHANGELOG.md.

⭐ License

This project is licensed under GNU General Public License 2.0 (or later).