README

Maestro is the first CLI agent built entirely in PHP with the Neuron AI framework. It brings powerful agentic capabilities to the PHP ecosystem through an elegant CLI tool that combines intelligent analysis with interactive tool approval.

Important

Get early access to new features, exclusive tutorials, and expert tips for building AI agents in PHP. Join a community of PHP developers pioneering the future of AI development. Subscribe to the newsletter

Before moving on, support the community giving a GitHub star ⭐️. Thank you!

About Maestro

While most CLI agents are written in Python or TypeScript, Maestro demonstrates that PHP can deliver a world-class AI experience. Built on the modern Neuron AI framework, Maestro provides:

• Native PHP Architecture: Every component—agent orchestration, CLI interface, event system—is implemented in PHP
• Tool Approval System: Interactive confirmation before the agent executes sensitive operations
• Multi-Provider AI Support: Choose from Anthropic Claude, OpenAI, Gemini, Cohere, Mistral, Ollama, Grok, or Deepseek
• MCP Integration: Extend capabilities with Model Context Protocol servers
• Sophisticated Output Rendering: Beautiful diffs, markdown rendering, and intuitive tool call visualization
• Customizable with Extensions: Powerful extension system that allows you to customize the agent by adding tools, inline commands, memories, and more

Full Introduction

For a full introduction to the project architecture, you can read the article below:

https://inspector.dev/maestro-a-customizable-cli-agent-built-in-php/

Requirements

• PHP >= 8.1
• Composer - Install Composer

Installation

If you are on a Windows machine, you should install and run Maestro in a WSL environment.

Install Maestro globally to use it in any project:

composer global require neuron-core/maestro

Ensure Composer's global bin directory is in your shell profile. Run echo $0 to find the current shell.

bash

echo 'export PATH="$(composer config -g home)/vendor/bin:$PATH"' >> ~/.bashrc

zsh

echo 'export PATH="$(composer config -g home)/vendor/bin:$PATH"' >> ~/.zshrc

Future Updates

To keep the tool up to date, run the global update:

composer global update

Configuration

When you run Maestro on a filesystem directory for the first time, it will ask you to configure your AI provider and API key.

cd /your/project/folder

maestro

It will start an interactive setup wizard that guides you through the configuration process.

Anthropic

{
    "default": "anthropic",
    "providers": {
        "anthropic": {
            "api_key": "sk-ant-your-api-key-here",
            "model": "claude-sonnet-4-6"
        }
    }
}

Ollama

{
    "default": "ollama",
    "providers": {
        "ollama": {
            "base_url": "http://localhost:11434",
            "model": "llama2"
        }
    }
}

For all supported providers you can check out the Neuron AI documentation: https://docs.neuron-ai.dev/providers/ai-provider

Context File Configuration

You can provide project-specific instructions by adding a context_file setting. The agent will load this file and append its content to its system instructions.

If no context_file is specified, the agent will look for Agents.md in the project root. If the file doesn't exist, no additional context is attached.

{
    "providers": {
        ...
    },
    "context_file": "CLAUDE.md"
}

MCP Servers

Add Model Context Protocol servers to extend the agent's capabilities:

{
    "providers": {
        ...
    },
    "mcp_servers": {
        "tavily": {
            "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>"
        }
    }
}

Note: The .maestro/settings.json file should be located in your current working directory when running maestro.

Usage

Start an interactive chat session:

# Mavigate to the project directory
cd path/project

# Start the maestro CLI
maestro

Tool Approval

When the agent proposes a tool operation, you'll be prompted to approve it. The human-in-the-loop system is powered by the Neuron AI Tool Approval middleware.

You can Choose from:

• Allow once: Approve this specific operation
• Allow for session: Approve all operations of this type during the current session
• Deny: Reject this operation

Monitoring Maestro sessions

Neuron AI is natively integrated with Inspector, allowing you to monitor and analyze your AI coding sessions. To enable agent monitoring you just need to add the inspector_key field to your .maestro/settings.json file:

{
    "providers": {
        ...
    },
    "inspector_key": "INSPECTOR_INGESTION_KEY"
}

You can get an INSPECTOR_INGESTION_KEY from the Inspector dashboard.

Extension Architecture

Maestro's extension system is the primary customization layer. Extensions are PHP classes that implement ExtensionInterface and register components through a single ExtensionApi object injected at boot time.

How it works

At startup, the ExtensionLoader builds a set of shared registries (tools, commands, renderers, events, memories, UI) and wires them into an ExtensionApi instance. Each extension's register() method is called with that API, allowing it to push into any registry. The agent then reads from those registries for the rest of the session.

composer.json (extra.maestro)
        │
        ▼
  .maestro/manifest.php  ──►  ExtensionLoader
  .maestro/settings.json ──►  (merges manifest + settings)
                                       │
                                       ▼
                              ExtensionApi (per extension)
                         ┌─────────────┴─────────────┐
                    register()                   register()
                         │                            │
              ┌──────────▼──────────────────────────┐
              │  ToolRegistry  CommandRegistry        │
              │  RendererRegistry  EventRegistry      │
              │  MemoryRegistry  UiEngine             │
              └──────────────────────────────────────┘
                         │
                         ▼
                   MaestroAgent (reads registries at runtime)

Extension components

Minimal extension

class MyExtension implements ExtensionInterface
{
    public function name(): string
    {
        return 'my-extension';
    }

    public function register(ExtensionApi $api): void
    {
        $api->registerTool($myTool);
        $api->registerCommand($myCommand);
        $api->registerRenderer('my_tool', $myRenderer);
    }
}

Discovery and loading

Extensions can be loaded two ways:

• Auto-discovery — declare them in your package's composer.json under extra.maestro.extensions. Maestro generates a manifest at .maestro/manifest.php via maestro discover (or composer dump-autoload).
• Manual registration — list them directly in .maestro/settings.json under the extensions key.

Settings always take precedence over the manifest, allowing users to override enabled status and pass configuration to any extension.

For a comprehensive guide covering packaging, auto-discovery, UI customization, and all available APIs, see the Extension README.

This repository also includes the skills directory to provide detailed instructions to AI coding assistants for extension development.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the FSL License - see the LICENSE file for details.

Credits

Built with:

• Neuron AI - PHP agentic framework
• Symfony Console - CLI component

Made with ❤️ by Inspector team