Symfony AI - Mate Component

Installation

1

$ composer require --dev symfony/ai-mate

Purpose

Symfony AI Mate is a development tool that gives your coding agent (Claude Code, Codex, GitHub Copilot, Cursor, JetBrains AI, etc.) specific knowledge about your PHP application and development environment.

Mate is a plain CLI: the agent runs vendor/bin/mate tools:call … the way it runs any other command. There is no server to start, no client-specific configuration file, and no permanent tool descriptions occupying the agent's context window. Any agent that can run a shell command can use Mate.

Mate reads your application without booting it: the compiled container is parsed from the dumped XML, the profiler and logs are read from disk. That means it still answers when the application itself does not boot, which is usually the moment you need it.

Important: This is intended for development and debugging only, not for production deployment.

This is the core package. It works with any PHP application - while it includes Symfony-specific tools via bridges, the core functionality is framework-agnostic.

Quick Start

Install with composer:

1

$ composer require --dev symfony/ai-mate

Initialize configuration:

1

$ vendor/bin/mate init

This creates:

• mate/ directory with configuration files
• mate/src directory for custom tools
• mate/AGENT_INSTRUCTIONS.md placeholder (refreshed by mate discover)
• a managed instruction block in AGENTS.md
• CLAUDE.md importing AGENTS.md via @AGENTS.md, so Claude Code picks the instructions up

It also updates your composer.json with the following configuration:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
    "autoload-dev": {
        "psr-4": {
            "Mate\\": "mate/src/"
        }
    },
    "extra": {
        "ai-mate": {
            "extension": false,
            "scan-dirs": ["mate/src"],
            "includes": ["mate/config.php"]
        }
    }
}

The extension: false flag prevents your application from being discovered as a reusable Mate extension when it is installed as a dependency elsewhere. Remove it, or set it to true, only if your package should be discoverable by other projects.

After running mate init, update your autoloader:

1

$ composer dump-autoload

Finally, install the skills:

1

$ vendor/bin/mate skills:install

This writes the SKILL.md files of every enabled extension into .agents/skills/, with a mirror in .claude/skills/. Do not skip this step. The instructions above tell an agent that Mate exists, but the skills are what tell it when to reach for which tool, and they are the file an agent trips over on its own while looking around a fresh checkout. mate discover runs the install for you, and so does Composer after composer require, so in practice you rarely call it by hand. See Skills.

Automatic Discovery

The symfony/ai-mate package installs the optional Composer plugin symfony/ai-mate-composer-plugin. After your project has been initialized and mate/extensions.php exists, Composer automatically runs:

1

$ vendor/bin/mate discover --composer

after composer install and composer update. This refreshes discovered extensions and regenerates the managed instruction artifacts.

Before initialization, the Composer plugin does not modify your project. It only prints a hint to run:

1

$ vendor/bin/mate init

Use vendor/bin/mate discover whenever you want to refresh extensions manually after changing Mate configuration, adding instructions, or working on local extensions.

Discover available extensions:

1

$ vendor/bin/mate discover

This command also refreshes:

• mate/AGENT_INSTRUCTIONS.md
• Managed AI Mate instruction section in AGENTS.md

Using Mate from a coding agent

There is nothing to start. Your agent discovers Mate through the instructions written into AGENTS.md and mate/AGENT_INSTRUCTIONS.md, and runs four commands:

1
2
3
4

$ vendor/bin/mate tools:list                          # what is available
$ vendor/bin/mate tools:inspect symfony-profiler-list # parameters and JSON input schema
$ vendor/bin/mate tools:call symfony-profiler-list --limit=1
$ vendor/bin/mate resources:read symfony-profiler://profile/<token>

Tool parameters are passed as long options, one per parameter, and coerced to the parameter's declared type. Booleans may be passed as a bare flag, and a variadic parameter collects the option repeated. For nested or associative values, and for parameter names that collide with a console option, pass a JSON object instead:

1
2
3

$ vendor/bin/mate tools:call monolog-search --term="^GET" --regex
$ vendor/bin/mate tools:call some-tool --tag=a --tag=b
$ vendor/bin/mate tools:call some-tool --json='{"filters": {"level": "error"}}'

All four accept --format. Use --format=json when the result is parsed, and --format=toon (requires helgesverre/toon) for the smallest context footprint.

Add Custom Tools

The easiest way to add tools is to create a mate/src folder next to your src and tests directories, then add a class with a public method carrying the #[MateTool] attribute:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// mate/src/MyTool.php
namespace Mate;

use Symfony\AI\Mate\Attribute\MateTool;

class MyTool
{
    /**
     * @param string $param The value to process
     */
    #[MateTool(name: 'my-tool', title: 'My Tool', description: 'My custom tool')]
    public function execute(string $param): array
    {
        return ['result' => $param];
    }
}

Mate discovers the method by reflection and derives its JSON input schema from the signature plus the @param PHPDoc, so the description you write there is what the agent sees in tools:inspect.

Two further attributes cover data the agent navigates into rather than calls:

• #[MateResource] marks a method as a static resource, addressed by a fixed uri.
• #[MateResourceTemplate] marks a method as a templated resource; the variables in its uriTemplate are passed to the method.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

use Symfony\AI\Mate\Attribute\MateResource;
use Symfony\AI\Mate\Attribute\MateResourceTemplate;

class MyResources
{
    #[MateResource(uri: 'my-app://config', name: 'config', mimeType: 'application/json')]
    public function config(): string
    {
        return json_encode(['debug' => true]);
    }

    #[MateResourceTemplate(uriTemplate: 'my-app://entity/{id}', name: 'entity')]
    public function entity(string $id): array
    {
        return ['id' => $id];
    }
}

Resources are read with vendor/bin/mate resources:read <uri>. The split is worth keeping in mind when designing your own: a tool is something the agent calls with arguments, a resource is something it addresses and can drill into, which keeps large payloads out of the context window until they are actually needed.

After adding a class under mate/src/, run composer dump-autoload if the autoloader does not know it yet. Verify with vendor/bin/mate tools:list.

Choosing the interpreter

Mate reads the compiled container, the profiler cache and the logs of this project, and extensions may behave differently per runtime. Running it under the wrong interpreter therefore does not just fail, it reports on something that is not the application under test.

mate init asks which command your coding agent should use and writes two parameters into mate/config.php:

1
2
3
4

$container->parameters()
    ->set('mate.invocation', 'ddev exec vendor/bin/mate')
    ->set('mate.php_version', '8.3')
;

mate.invocation

The full command the agent must use, wrapper included. It is materialized into mate/AGENT_INSTRUCTIONS.md and the managed AGENTS.md block, so the prefix ends up where the agent actually reads it. When a .ddev/ directory is present, mate init proposes ddev exec vendor/bin/mate as the default. Answering with a wrapper alone is enough, symfony php is recorded as symfony php vendor/bin/mate. Left at its default, the value is the plain vendor/bin/mate and nothing is prefixed anywhere.

mate.php_version

The PHP version the project runs on, recorded as major.minor. When mate.invocation wraps the binary, mate init runs php through that wrapper to find out which interpreter it really reaches, rather than recording the one that happened to run init. If the wrapper cannot be reached, init warns and falls back to the current process, and you should check the value by hand. Mate refuses to start under a different one and points at mate.invocation in the error:

1
2
3
4

$ vendor/bin/mate tools:list

 [ERROR] Mate is running under PHP 8.4.15 but this project expects PHP 8.3.
         Run it as "ddev exec vendor/bin/mate". ...

Set the parameter to null to disable the check.

init, list, help and completion stay callable under any interpreter, because init is the command that writes this configuration in the first place and the others never read the application. They print a warning instead, so a wrong interpreter is visible before it reaches a command that does refuse.

Configuration

The configuration folder is called mate and is located in your project's root directory. It contains two important files:

• mate/extensions.php - Enable/disable extensions
• mate/config.php - Configure settings

1
2
3
4

$ vendor/bin/mate discover        # register newly installed extensions and install their skills
$ vendor/bin/mate skills:install  # rebuild the generated skill folders from the recorded state
$ vendor/bin/mate skills:list     # show which skills are enabled and how they are installed
$ vendor/bin/mate skills:validate # check the generated folders against the recorded state

1
2
3
4
5
6
7
8
9

// mate/extensions.php
// This file is managed by Mate - use `discover` or `skills:*` commands
// over manual editing. Only changes to `mode` or `enabled` are kept,
// every other key is overwritten by Mate.

return [
    'vendor/package-name' => ['enabled' => true],
    'vendor/another-package' => ['enabled' => false],
];

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// mate/config.php
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $container): void {
    $container->parameters()
        // Override default parameters here
        // ->set('mate.cache_dir', sys_get_temp_dir().'/mate')
        // ->set('mate.env_file', '.env') // Loads the project's own .env and .env.local
    ;

    $container->services()
        // Register your custom services here
    ;
};

1
2
3
4
5
6
7
8

use Symfony\AI\Mate\Container\MateHelper;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $container): void {
    MateHelper::disableFeatures($container, [
        'symfony/ai-mate' => ['server-info'],
    ]);
};

Adding Third-Party Extensions

1. Install the package:

   1

   $ composer require vendor/symfony-tools

2. Discover available tools (auto-generates/updates mate/extensions.php):

   1

   $ vendor/bin/mate discover

   When the project has already been initialized, Composer also refreshes discovery automatically after composer install and composer update.

3. Optionally disable specific extensions:

   1
   2
   3
   4
   5

   // mate/extensions.php
   return [
       'vendor/symfony-tools' => ['enabled' => true],
       'vendor/unwanted-tools' => ['enabled' => false],
   ];

To create a third party extension, see Creating Mate Extensions.

Available Bridges

1
2

$container->parameters()
    ->set('ai_mate_symfony.cache_dir', '%mate.root_dir%/var/cache');

1
2
3
4
5

$container->parameters()
    ->set('ai_mate_symfony.cache_dir', [
        'website' => '%mate.root_dir%/var/cache/website',
        'admin' => '%mate.root_dir%/var/cache/admin',
    ]);

1
2

$container->parameters()
    ->set('ai_mate_symfony.profiler_dir', '%mate.root_dir%/var/cache/dev/profiler');

1
2
3
4
5

$container->parameters()
    ->set('ai_mate_symfony.profiler_dir', [
        'website' => '%mate.root_dir%/var/cache/website/dev/profiler',
        'admin' => '%mate.root_dir%/var/cache/admin/dev/profiler',
    ]);

1
2
3
4
5
6
7
8

# Find the failed requests
$ vendor/bin/mate tools:call symfony-profiler-list --statusCode=500 --limit=20

# See which collectors that profile actually has
$ vendor/bin/mate resources:read symfony-profiler://profile/abc123

# Read one of them
$ vendor/bin/mate resources:read symfony-profiler://profile/abc123/exception

1
2

$container->parameters()
    ->set('ai_mate_monolog.log_dir', '%mate.root_dir%/var/log');

1
2
3
4
5

$container->parameters()
    ->set('ai_mate_monolog.log_dir', [
        'website' => '%mate.root_dir%/var/log/website',
        'admin' => '%mate.root_dir%/var/log/admin',
    ]);

Built-in Tools

The core package provides basic system information tools:

• server-info - Get PHP runtime environment details: version, OS, OS family, and loaded extensions

Skills

Agent Skills are SKILL.md files that give your coding agent structured, multi-step "how-to" knowledge for a task. Extensions can ship skills alongside their tools, and Mate installs them onto the filesystem where coding agents read them.

Skills are what make the CLI findable. A tool that exists but is never invoked is worth nothing, and a bare CLI is invisible to an agent that was never told about it. The skills describe when to reach for which tool and in what order, which is the difference between Mate being installed and Mate being used.

You usually do not run anything: mate discover (which also runs automatically after composer require) installs the skills of every enabled extension. To sync them manually, use mate skills:install.

Each skill is installed under a mate- prefixed directory name (e.g. mate-demo-skill) to avoid clashing with skills you maintain from other sources; the name in the installed SKILL.md is rewritten to match. Skills land in two locations:

• .agents/skills/ is the source of truth, read directly by Codex, OpenCode and GitHub Copilot.
• .claude/skills/ mirrors .agents/skills/ via relative symlinks for Claude Code, which only reads its own directory.

Both folders are generated output: skills:install is an idempotent reconciler that rebuilds them from source on every run and prunes skills that are gone or disabled. Do not edit them by hand, your changes are overwritten on the next run and reported as errors by mate skills:validate.

Skills are copied, never symlinked into vendor/. What your agent loads is a real file you can open and diff, and a package update cannot silently change it underneath you. Mate does not touch your .gitignore: committing the generated folders is recommended, because it turns an upstream skill change into a reviewable diff instead of something that lands silently.

All skill state lives in mate/extensions.php. Two keys per skill carry your intent:

• enabled controls whether the skill is installed at all. Use mate skills:disable <name> and mate skills:enable <name> to flip it.
• mode is either managed, where Mate builds the skill from the package, or override, which hands ownership to you: Mate then builds from your own mate/skills/<name>/ copy and never writes into mate/skills/. Use mate skills:override <name> to switch, and mate skills:reset <name> to hand the skill back.

The skills:* commands set both for you, which is the recommended way to change them, and they also reinstall, so the recorded state below never falls out of step with your intent. Editing the two keys by hand works as well; the next install picks the change up.

Everything else is written by Mate and rewritten on every install; the resulting state (managed, override or disabled), the source it was built from, the source_hash and hash pair used to detect drift, and the generated targets:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// mate/extensions.php
return [
    'vendor/package' => [
        'enabled' => true,
        'skills' => [
            'demo-skill' => [
                'enabled' => true,
                'mode' => 'managed',
                'state' => 'managed',
                'source' => 'vendor/vendor/package/skills/demo-skill',
                'source_hash' => 'sha256:...',
                'hash' => 'sha256:...',
                'targets' => [
                    '.agents/skills/mate-demo-skill',
                    '.claude/skills/mate-demo-skill',
                ],
            ],
        ],
    ],
];

Use mate skills:list for an overview, and mate skills:validate to check the generated folders against that record: it reports hand-edited content, missing folders, and sources that moved on since the last install. It also looks at the installed content itself: it warns when a Markdown link points at a file that is not part of the skill, and suggests a better description when it is too short or never says when the skill applies, because that description is all an agent has when it decides whether to load the skill. Those description findings are suggestions, not warnings: they are printed but never change the exit code, not even with --strict. mate skills:prune removes leftover mate-* folders.

To see what an install would do before it does it, run mate skills:install --dry-run: the same reconciler runs and reports what it would install, rebuild or remove, but nothing is written.

A skill ships with the extension whose tools it drives, so a project only ever installs skills it can actually follow. The core package ships two:

php-environment-check

Establish whether a failing tool is the PHP runtime rather than the application.

system-information

Resolve which dependency versions are actually installed, via composer show and composer.lock.

The Symfony extension adds three:

symfony-profiler-debugging

Diagnose a request that errored or was slow, through the profiler: which profile to find, which collectors to read, and in what order depending on the symptom.

symfony-request-triage

Decide which of the other skills a given symptom calls for.

symfony-service-inspection

Inspect the compiled DI container when the wiring, not the code, is the suspect.

And the Monolog extension one:

symfony-log-investigation

Investigate trends across requests in the Monolog log files, rather than one failed request.

Commands

mate init

Initialize AI Mate configuration and create the mate/ directory.

mate discover

Scan for Mate extensions in installed packages. This command will:

• Scan your vendor directory for packages with extra.ai-mate configuration
• Generate or update mate/extensions.php with discovered extensions
• Preserve existing enabled/disabled states for known extensions
• Default new extensions to enabled
• Install Agent Skills shipped by enabled extensions (see Skills)

mate skills:install

Install the Agent Skills shipped by your enabled extensions so your coding agent can use them. This runs automatically as part of mate discover; use it for an explicit re-sync. Pass --dry-run to see what a run would install, rebuild or remove without writing anything. See Skills.

mate skills:list

List declared and installed skills with their enabled, mode, state and status information. Read-only diagnostic. See Skills.

mate skills:validate

Check the generated skill folders against the state recorded in mate/extensions.php, and the installed content itself for dead links and descriptions an agent cannot act on. Exits with a non-zero status when a skill is broken; pass --strict to fail on warnings too. Suggestions about a description never affect the exit code. Read-only. See Skills.

mate skills:prune

Remove generated mate-* folders that no longer belong to any skill. Pass --dry-run to see what would be removed. See Skills.

mate skills:override <name>

Take ownership of a skill: copy the package's version into mate/skills/<name>/ and switch it to 'mode' => 'override'. Accepts the installed (mate-…) or the original name. Pass --force to replace an existing copy. See Skills.

mate skills:reset <name>

Hand an overridden skill back to Mate, so it is built from the package again. Your copy under mate/skills/<name>/ is kept unless you pass --delete-copy. See Skills.

mate skills:disable <name>

Hide a skill from coding agents: remove its generated folders and record it as disabled. The entry stays in mate/extensions.php, and a copy of your own under mate/skills/ is left untouched. See Skills.

mate skills:enable <name>

Make a disabled skill visible again and rebuild its generated folders. See Skills.

mate clear-cache

Clear the cache.

mate debug:capabilities

Display all discovered capabilities grouped by extension. This command is useful for:

• Verifying extension installation and capability registration
• Debugging missing or misconfigured extensions
• Understanding which package provides each capability
• Inspecting available tools during development

Options:

--format=FORMAT

Output format: text (default), json, or toon. The toon format requires helgesverre/toon.

--extension=EXTENSION

Filter by extension package name (e.g., symfony/ai-monolog-mate-extension)

--type=TYPE

Filter by capability type: tool, resource, or template

Examples:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Show all capabilities
$ vendor/bin/mate debug:capabilities

# Show only tools
$ vendor/bin/mate debug:capabilities --type=tool

# Show capabilities from specific extension
$ vendor/bin/mate debug:capabilities --extension=symfony/ai-monolog-mate-extension

# JSON output for scripting
$ vendor/bin/mate debug:capabilities --format=json

# TOON output for token-efficient inspection
$ vendor/bin/mate debug:capabilities --format=toon

# Root project capabilities
$ vendor/bin/mate debug:capabilities --extension=_custom

mate debug:extensions

Display detailed information about discovered and loaded Mate extensions. This command is useful for:

• Understanding which extensions are discovered vs enabled vs loaded
• Debugging extension loading issues
• Verifying extension configuration from mate/extensions.php
• Inspecting scan directories and include files
• Troubleshooting why an extension isn't providing capabilities

Status Indicators:

[enabled]

Extension is configured to load in mate/extensions.php

[loaded]

Extension successfully loaded into the DI container

[not loaded]

Extension failed to load (package removed, error, etc.) - useful for troubleshooting

Options:

--format=FORMAT

Output format: text (default), json, or toon. The toon format requires helgesverre/toon.

--show-all

Show all discovered extensions including disabled ones

Examples:

1
2
3
4
5
6
7
8
9
10
11

# Show enabled extensions
$ vendor/bin/mate debug:extensions

# Show all extensions (including disabled)
$ vendor/bin/mate debug:extensions --show-all

# JSON output for scripting
$ vendor/bin/mate debug:extensions --format=json

# TOON output for token-efficient inspection
$ vendor/bin/mate debug:extensions --format=toon

mate tools:list

List all available tools with their metadata. This command provides a compact overview of tools for quick reference and filtering.

Options:

--filter=PATTERN

Filter tools by name pattern (supports wildcards like search* or *logs)

--extension=EXTENSION

Filter tools by extension package name

--format=FORMAT

Output format: table (default), json, or toon. The toon format requires helgesverre/toon.

Examples:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# List all tools
$ vendor/bin/mate tools:list

# Filter by name pattern
$ vendor/bin/mate tools:list --filter="monolog*"
$ vendor/bin/mate tools:list --filter="*search"

# Show tools from specific extension
$ vendor/bin/mate tools:list --extension=symfony/ai-monolog-mate-extension

# JSON output for scripting
$ vendor/bin/mate tools:list --format=json

# Combined filters
$ vendor/bin/mate tools:list --extension=symfony/ai-monolog-mate-extension --filter="*search"

mate tools:inspect

Display detailed information about a specific tool including its full JSON input schema. This command is useful for understanding tool parameters and requirements.

Arguments:

tool-name

Name of the tool to inspect (required)

Options:

--format=FORMAT

Output format: text (default), json, or toon. The toon format requires helgesverre/toon.

Examples:

1
2
3
4
5
6
7
8

# Inspect a specific tool
$ vendor/bin/mate tools:inspect server-info

# Inspect extension tool
$ vendor/bin/mate tools:inspect monolog-search

# JSON output for scripting
$ vendor/bin/mate tools:inspect server-info --format=json

mate tools:call

Execute a tool, passing each of its parameters as a long option.

Arguments:

tool-name

Name of the tool to execute (required)

Options:

--<param>=<value>

One option per tool parameter. Values are coerced to the parameter's declared type. A boolean parameter may be passed as a bare --<flag>. Repeat the option to pass several values to a variadic parameter; repeating it on a single-value parameter is an error rather than a silent last-one-wins.

--json=JSON

Tool parameters as a JSON object, merged under any --<param> options. Use this for nested or associative values, and for parameter names shadowed by a console option (format, json, help, silent, quiet, verbose, version, ansi, no-ansi, no-interaction).

--format=FORMAT

Output format: pretty (default), json, or toon. The toon format requires helgesverre/toon.

Examples:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Execute a tool without parameters
$ vendor/bin/mate tools:call server-info

# Execute a tool with parameters
$ vendor/bin/mate tools:call monolog-search --term=error --level=error

# Boolean parameters may be passed as bare flags
$ vendor/bin/mate tools:call monolog-search --term="^GET" --regex

# Complex or array parameters
$ vendor/bin/mate tools:call some-tool --json='{"tags": ["a", "b"]}'

# JSON output format
$ vendor/bin/mate tools:call server-info --format=json

# TOON output for token-efficient inspection
$ vendor/bin/mate tools:call server-info --format=toon

mate resources:read

Read a resource by its URI. Matches both static resources and resource templates; for a template, the variables in the URI are passed to the handler.

Arguments:

uri

URI of the resource to read (required)

Options:

--format=FORMAT

Output format: pretty (default), json, or toon. The toon format requires helgesverre/toon.

Examples:

1
2
3
4
5
6
7
8

# List the collectors a profile actually has
$ vendor/bin/mate resources:read symfony-profiler://profile/abc123

# Read one collector
$ vendor/bin/mate resources:read symfony-profiler://profile/abc123/db

# JSON output for scripting
$ vendor/bin/mate resources:read symfony-profiler://profile/abc123 --format=json

Security

Discovered extensions are written to mate/extensions.php and new entries default to enabled: true. Disable specific packages by setting their enabled flag to false.

Packages that set extra.ai-mate.extension to false are excluded from discovery entirely.

Further Reading