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 & Console](/categories/cli) 4. / 5. neuron-core/maestro ActiveLibrary[CLI & Console](/categories/cli) neuron-core/maestro =================== AI Coding Assistant built entirely in PHP with Neuron AI framework 1.3.1(1mo ago)19351FSL-1.1-MITPHPPHP ^8.1 Since Mar 6Pushed 1mo ago1 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 1mo ago 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 >= 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 46 — FairBetter than 93% of packages Maintenance90 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 50d 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.6k331.8M8.4k](/packages/nunomaduro-collision)[fidry/console Library to create CLI applications 192.0M4](/packages/fidry-console)[mahocommerce/maho Free and open source ecommerce platform, created in 2024 on the M1 platform, PHP 8.3+ 1322.1k12](/packages/mahocommerce-maho)[duncan3dc/console Create command line php applications using symfony/console 17263.4k1](/packages/duncan3dc-console)[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)