Open sandboxFocusImprove this doc

Configuring AI agents

AI coding agents such as Claude Code and OpenAI Codex generate much better Metalama code when they can look up the real documentation instead of guessing from memory. The Metalama plugin gives them comprehensive knowledge about aspects, templates, fabrics, and the entire Metalama API.

What the plugin provides

The Metalama plugin gives your AI agent access to:

  • Conceptual documentation: Complete guides on aspects, templates, fabrics, validation, and configuration.
  • API reference: Full documentation for all Metalama namespaces and types.
  • Sample code: Working examples demonstrating common patterns and techniques.
  • Pattern libraries: Documentation for Metalama.Patterns.Contracts, Metalama.Patterns.Caching, Metalama.Patterns.Observability, and more.

Installing in Claude Code

  1. Add the Metalama marketplace to Claude Code:

    /plugin marketplace add https://github.com/metalama/Metalama.AI.Skills
    
  2. Install the Metalama plugin:

    /plugin install metalama
    

To update to a newer version:

/plugin update metalama

Installing in OpenAI Codex

  1. Add the Metalama marketplace to Codex:

    codex plugin marketplace add metalama/Metalama.AI.Skills
    
  2. Install the metalama plugin from the plugin directory (Plugins) in the Codex app.

To update to a newer version:

codex plugin marketplace upgrade

Using the plugin

Once installed, the agent automatically uses the Metalama plugin when you ask questions about:

  • Creating or modifying aspects
  • Writing T# templates
  • Using fabrics to apply aspects in bulk
  • Working with the Metalama code model
  • Implementing patterns like caching, contracts, or observability

If the agent doesn't seem to use Metalama-specific knowledge, explicitly mention "Metalama" in your prompt.

Letting the agent see the generated code

An agent cannot use the Metalama Diff of Visual Studio. To check the code that an aspect generates, it must read the transformed code. The fastest way is the metalama preview command, which prints the transformed and formatted code of one or a few files without building the whole project:

metalama preview src/MyProject/Services/OrderService.cs

The Metalama plugin tells the agent to use this command after it changes an aspect or the code that an aspect targets. The command belongs to the Metalama command line tool, so install the tool on the machine where the agent runs:

dotnet tool install -g metalama.tool

For details, see Previewing transformed code from the command line.

Letting the agent query the aspects

When an agent reads code to which aspects apply, the source code does not show what the aspects do. An agent cannot use the Aspect Explorer of Visual Studio either. The metalama introspect command answers these questions from the command line: which aspects apply to a declaration, what created them, which transformations they make and in which order, and which diagnostics they reported.

The command reads the introspection file of the last build. The build writes this file only when the MetalamaWriteIntrospectionFile MSBuild property is True. To query the aspects of a declaration, the agent follows these steps:

  1. Set the MetalamaWriteIntrospectionFile environment variable to True in its session. The variable affects only the builds of this session, so the other builds do not pay for the file.

    $env:MetalamaWriteIntrospectionFile = "True"
    
  2. Build the project. A normal build is enough: it compiles the project again when the property changes.

    dotnet build
    
  3. Query the declaration, for instance by its position in the source file:

    metalama introspect show declaration src/MyProject/Services/OrderService.cs:42
    

The command belongs to the same command line tool as metalama preview.

For details, see Querying aspects from the command line.

Example prompts

  • "Create a logging aspect that logs method entry and exit"
  • "How do I introduce a property to a class using Metalama?"
  • "Write a contract that validates a string parameter is not empty"
  • "How do I apply an aspect to all public methods in a namespace?"