PHPackages                             neuron-core/maestro - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI &amp; Console](/categories/cli)
4. /
5. neuron-core/maestro

ActiveLibrary[CLI &amp; Console](/categories/cli)

neuron-core/maestro
===================

AI Coding Assistant built entirely in PHP with Neuron AI framework

1.3.1(yesterday)19351FSL-1.1-MITPHPPHP ^8.1

Since Mar 6Pushed yesterday1 watchersCompare

[ Source](https://github.com/neuron-core/maestro)[ Packagist](https://packagist.org/packages/neuron-core/maestro)[ Docs](https://github.com/neuron-core/maestro)[ RSS](/packages/neuron-core-maestro/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (8)Versions (47)Used By (0)

Maestro - The First CLI Agent built in PHP
==========================================

[](#maestro---the-first-cli-agent-built-in-php)

**Maestro** is the first CLI agent built entirely in PHP with the [Neuron AI framework](https://github.com/neuron-core/neuron-ai). It brings powerful agentic capabilities to the PHP ecosystem through an elegant CLI tool that combines intelligent analysis with interactive tool approval.

[![PHP](https://camo.githubusercontent.com/83dd395020c37276225039739320f6c8e7e99963ab21ee3d09282cb48dad2a60/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c7565)](https://camo.githubusercontent.com/83dd395020c37276225039739320f6c8e7e99963ab21ee3d09282cb48dad2a60/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c7565)

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](https://neuron-ai.dev)

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

[![](assets/maestro.png)](https://www.youtube.com/watch?v=F01ZQWSAsw0)

About Maestro
-------------

[](#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](https://docs.neuron-ai.dev), 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
-----------------

[](#full-introduction)

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

Requirements
------------

[](#requirements)

- PHP &gt;= 8.1
- Composer - [Install Composer](https://getcomposer.org/download/)

Installation
------------

[](#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
--------------

[](#future-updates)

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

```
composer global update
```

Configuration
-------------

[](#configuration)

Before using Maestro, you need to configure your AI provider and API key. Navigate to the project directory you want to use Maestro in and run the command below:

```
maestro init
```

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

#### Anthropic

[](#anthropic)

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

#### Ollama

[](#ollama)

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

For all supported providers you can check out the Neuron AI documentation:

### Context File Configuration

[](#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

[](#mcp-servers)

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

```
{
    "providers": {
        ...
    },
    "mcp_servers": {
        "tavily": {
            "url": "https://mcp.tavily.com/mcp/?tavilyApiKey="
        }
    }
}
```

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

Usage
-----

[](#usage)

Start an interactive chat session:

```
# Mavigate to the project directory
cd path/project

# Start the maestro CLI
maestro
```

### Tool Approval

[](#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](https://docs.neuron-ai.dev/agent/middleware#tool-approval-human-in-the-loop) 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
---------------------------

[](#monitoring-maestro-sessions)

Neuron AI is natively integrated with [Inspector](https://inspector.dev), 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](https://app.inspector.dev/register).

Extension Architecture
----------------------

[](#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

[](#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

[](#extension-components)

ComponentAPI methodPurposeAI Tools`registerTool()`New capabilities the agent can invoke (filesystem, HTTP, etc.)Inline Commands`registerCommand()``/slash` commands available in the interactive consoleRenderers`registerRenderer()`Custom terminal output for a specific tool's resultEvent Handlers`on()`React to agent lifecycle events (thinking, response, tool approval)Memory Files`registerMemory()`Markdown files injected into the agent's system promptUI / Widgets`registerWidget()`, `ui()`Slots, themes, and widgets for terminal interface customization### Minimal extension

[](#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

[](#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](src/Extension/README.md)**.

This repository also includes the [skills](./skills) directory to provide detailed instructions to AI coding assistants for extension development.

Contributing
------------

[](#contributing)

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

License
-------

[](#license)

This project is licensed under the FSL License - see the [LICENSE](LICENSE) file for details.

Credits
-------

[](#credits)

Built with:

- [Neuron AI](https://docs.neuron-ai.dev/) - PHP agentic framework
- [Symfony Console](https://symfony.com/doc/current/console.html) - CLI component

---

Made with ❤️ by [Inspector](https://inspector.dev) team

###  Health Score

49

—

FairBetter than 95% of packages

Maintenance100

Actively maintained with recent releases

Popularity20

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

46

Last Release

1d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/320345fbe48c7cff2b3a25992c8207e959ae7817fb2fb97bb176dc6e559aacf5?d=identicon)[valerione](/maintainers/valerione)

---

Top Contributors

[![ilvalerione](https://avatars.githubusercontent.com/u/13559278?v=4)](https://github.com/ilvalerione "ilvalerione (224 commits)")

---

Tags

aiai-agentscode-generationcoding-assistantneuronphpclisymfonyaicodingneuron-aiassistant

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/neuron-core-maestro/health.svg)

```
[![Health](https://phpackages.com/badges/neuron-core-maestro/health.svg)](https://phpackages.com/packages/neuron-core-maestro)
```

###  Alternatives

[nunomaduro/collision

Cli error handling for console/command-line PHP applications.

4.6k324.1M7.0k](/packages/nunomaduro-collision)[fidry/console

Library to create CLI applications

191.9M2](/packages/fidry-console)[mahocommerce/maho

Free and open source ecommerce platform, created in 2024 on the M1 platform, PHP 8.3+

1271.5k12](/packages/mahocommerce-maho)[eddiriarte/console-select

A fancy selection interface for symfony's console component.

117.2k2](/packages/eddiriarte-console-select)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
