MerchantDuo

MerchantDuo is a Pi coding agent for Magento 2.4 teams. It starts from the store's selected environment, Magento version, deployment mode, and theme context instead of treating a Magento project as a generic repository.

Overview

• Works with local checkouts, Warden, and SSH environments.
• Detects Magento edition, version, PHP version, deployment mode, cache types, and registered theme inheritance.
• Ships Magento 2.4, Luma, Hyva, Mage2Gen, testing, and persistent-goal skills.
• Provides guided local/Warden store provisioning.
• Keeps remote writes and Magento operations behind explicit execution boundaries.

At session start, MerchantDuo produces a Magento snapshot from the selected environment. Frontend and admin URLs are discovered but remain unverified until an explicit test. The compact status line shows the Magento version, environment lifecycle, session permission mode, an explicit theme scope when one is selected, and the frontend URL when available.

Commands and tools

Extension slash commands are namespaced with duo- to avoid collisions with other Pi extensions.

• Command reference covers session theme and permission switching, lifecycle, navigation, and bundled persistent-goal commands.
• Tool reference covers workspace, environment, Magento workflow, magerun2, testing, PHP-console, and optional knowledge tools, including parameters and confirmation boundaries.

Environments

Define the environments your team uses in .merchantduo.yaml, then select one at launch with --env.

defaultEnvironment: local
activeTheme: all
testing:
  frontendUrl: https://shop.example.test/
  adminUrl: https://shop.example.test/admin/
  allowInsecureTls: true
environments:
  local:
    type: local
    root: .
  warden:
    type: warden
    projectRoot: .
    root: /var/www/html
    filesService: php-fpm
    targets:
      default: php-fpm
      debug: php-debug
  stage:
    type: ssh
    host: shop-stage
    root: /var/www/html

Local uses the checkout directly. Warden routes project and Magento execution through its configured service. Local and Warden sessions start in normal; SSH starts in read-only. Run /duo-switch-permissions to choose a mode interactively, or provide <read-only|normal|yolo> directly to change only the current session; merchantduo --yolo starts in yolo. Configure SSH user, port, and key through an OpenSSH host alias:

Host shop-stage
  HostName stage.example.com
  User deploy
  Port 2222
  IdentityFile ~/.ssh/id_ed25519

Use that alias as host: shop-stage. Every merchantduo init asks “Choose what fits you most” and saves the selected role under the current user's ~/.merchantduo/operator-profile.yaml: store admin, backend developer, frontend developer, or full-stack developer. It then offers local first and Warden when its project .env is detected; it prints an SSH example instead of writing an unused remote environment. The role is optional to load and gives the agent context for explanations and recommendations only; it does not change tools or permissions. Project configuration contains no user identity and is safe to share in a repository.

Provisioning

Provision a local or Warden developer store from an empty directory or an existing Magento checkout:

merchantduo provision
merchantduo provision --env warden

This opens plain Pi in the host shell, even when the project defaults to Warden. It shares MerchantDuo’s configured Pi authentication, models, and user settings, but does not load the MerchantDuo package or initialize Magento context. The agent first inspects the real project, Warden/local runtime, Composer platform requirements, Magento state, and source/database evidence. It does not run a fixed Composer, database, Magento, lifecycle, or web-server sequence. Before a material mutation, it explains the evidence and intended effect and waits for confirmation. In particular, lock-file PHP incompatibility is diagnosed rather than bypassed with composer update. Unlike normal MerchantDuo sessions, provisioning may inspect and configure Magento deployment configuration such as app/etc/env.php and app/etc/config.php when needed; it must not reveal credentials or tokens in chat, commands, logs, or generated files.

Install and start

MerchantDuo requires Node.js 22.19 or later, Bash, and Python 3. HTTP/browser testing additionally needs curl and Chrome or Chromium. The bundled fetch_content internet-research tool runs over host HTTP and has no browser or Python-runner prerequisite. Warden and SSH environments need Warden and OpenSSH respectively.

pnpm install --frozen-lockfile
merchantduo init
merchantduo doctor --env local
merchantduo --env local

Review the generated .merchantduo.yaml before the first session. MerchantDuo requires a one-time configuration trust decision; set MERCHANTDUO_TRUST_CONFIG=1 only after review.

Safety and optional services

Normal MerchantDuo sessions do not load app/etc/env.php, credentials, or tokens into agent context. The separate provisioning session may configure Magento deployment files, but never reveals their secret values. MerchantDuo does not run background tests, cache commands, deployment actions, browser operations, or PHP code. Explicit operations use the confirmation rules described in the tool reference.

Set MERCHANTDUO_MCP_TOKEN to enable the built-in read-only knowledge tool. Set MERCHANTDUO_LLM_TOKEN to enable the built-in MerchantDuo provider. Neither endpoint is project configuration.

Development

pnpm install --frozen-lockfile
pnpm check
pnpm test
npm pack --dry-run

For the extension layout, provisioning boundary, and session lifecycle, see the architecture notes.