How to Build a PHP Coding Agent with Neuron AI’s Maestro Framework

What is Neuron?

Neuron is a PHP framework designed for agentic applications. It handles orchestration, data loading, and debugging, allowing developers to focus on the creative core of AI entities. The framework leverages PHP 8+ strong typing, with every method, property, and return value type‑checked by PHPStan.

Strong‑type system

All signatures and properties are explicitly typed, and the codebase passes 100% strict PHPStan checks.

IDE friendliness

Rich PHPDoc comments combined with strict typing give IDEs precise autocompletion for agent configuration, tool parameters, and response handling, facilitating long‑term maintenance and integration with frameworks like Symfony and Laravel.

Well‑designed architecture

Neuron uses standard PSR interfaces and minimizes external dependencies, reducing version conflicts and avoiding dependency‑hell. The same patterns work across micro‑services, WordPress plugins, or enterprise Symfony/Laravel projects.

Community‑driven

The design encourages contributions from the whole PHP ecosystem, resulting in robust implementations, broad test coverage, rapid feature iteration, and strong newcomer support.

What does a coding agent actually do?

Maestro is not a code‑completion tool; it is an autonomous agent that reads project files, reasons about the codebase, and proposes modifications. It operates in a loop: receive a task, decide which tools to invoke (read files, search patterns, write changes), execute them sequentially, and report results.

The key concept is “propose”: before touching the file system, the agent asks for user approval, implementing a human‑in‑the‑loop workflow interruption to mitigate risk.

Architecture Overview

The repository’s entry point is bin/maestro, a Symfony Console command. The structure is:

bin/maestro
└─ MaestroCommand (Symfony Console)
   ├─ Settings (.maestro/settings.json)
   ├─ EventDispatcher + CliOutputListener
   └─ AgentOrchestrator
       └─ CodingAgent (extends NeuronAI Agent)
           ├─ ProviderFactory → AIProviderInterface
           ├─ FileSystemToolkit (read‑only)
           └─ McpConnector[] (optional MCP servers)

CodingAgent inherits from Neuron’s Agent base class and adds a tool‑approval middleware. Before writing a file, it emits a ToolApprovalRequestedEvent and pauses execution. AgentOrchestrator captures the pause, prompts the user via CLI, and resumes or aborts based on the response.

Getting Started

Install globally (recommended): composer global require neuron-core/maestro Ensure the Composer global bin directory is in PATH:

export PATH="$HOME/.config/composer/vendor/bin:$PATH"

Alternatively, add it as a project dependency and run vendor/bin/maestro.

Create a .maestro/settings.json at the project root with at least a provider and API key:

{
  "provider": {
    "type": "anthropic",
    "api_key": "sk-ant-your-key-here",
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 8192
  }
}

Maestro supports Anthropic, OpenAI, Gemini, Cohere, Mistral, Ollama, Grok, Deepseek, etc., routing automatically based on the type field.

For fully local execution, use Ollama:

{
  "provider": {
    "type": "ollama",
    "base_url": "http://localhost:11434",
    "model": "llama2"
  }
}

Providing Project Context

By default Maestro loads Agents.md from the project root. You can specify another Markdown file (e.g., CLAUDE.md or PROJECT_RULES.md) in settings.json:

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

The content of this file is appended to the system prompt, giving the agent knowledge of project conventions such as PSR‑12, dependency injection preferences, etc.

Tool Approval Process

When the agent wants to modify a file, it pauses and displays options:

Agent wants to write to src/Service/UserService.php
[1] Allow once
[2] Allow for this session
[3] Always allow
[4] Deny

Option [2] Allow for this session is the most common, approving the operation for the current session without further prompts. [3] Always allow persists the choice in .maestro/settings.json under allowed_tools, skipping prompts in future sessions.

Event System

Maestro uses a lightweight PSR‑14 compatible event dispatcher with three main events: AgentThinkingEvent – triggered before each AI call. AgentResponseEvent – triggered when the model returns a response. ToolApprovalRequestedEvent – triggered when a tool needs approval. CliOutputListener subscribes to these events and handles all terminal rendering. This separation keeps the core agent logic independent of the output layer, allowing the same agent to be used in a web UI by swapping the listener.

MCP Integration (Extending Capabilities)

For teams needing capabilities beyond the file system, Maestro can configure Model Context Protocol (MCP) servers:

{
  "mcp_servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"}
    }
  }
}

Each entry spawns a subprocess that becomes an additional tool source, enabling the agent to perform GitHub operations, web searches, or any MCP‑compatible service alongside native file tools.

What Does This Prove?

Maestro demonstrates that patterns previously implemented only in Python or TypeScript can be fully expressed in PHP. The workflow‑centric architecture provides tool approval, human‑in‑the‑loop interruptions, event‑driven rendering, multi‑model abstraction, and MCP integration without leaving the PHP ecosystem.

The real engine is the Neuron AI framework, especially its v3 workflow capabilities; without the ability to pause the agent loop and resume based on user input, the tool‑approval system would require extensive scaffolding.

Source code: https://github.com/neuron-core/maestro

Documentation: https://docs.neuron-ai.dev