### Recommended WSL2 Setup for Maestro Source: https://docs.runmaestro.ai/installation This snippet outlines the recommended steps for cloning, installing dependencies, and running Maestro in development mode within a WSL2 environment. It emphasizes cloning the repository to the native Linux filesystem to prevent common issues. ```bash # Clone to Linux filesystem (not /mnt/...) cd ~ git clone https://github.com/RunMaestro/Maestro.git cd maestro # Install dependencies npm install # Run in development mode npm run dev ``` -------------------------------- ### Building Maestro from Source Source: https://docs.runmaestro.ai/installation This code block provides the necessary commands to build Maestro from its source code. It includes cloning the repository, installing Node.js dependencies, and running the development server or building for production. Prerequisites like Node.js version are also mentioned. ```bash # Prerequisites: Node.js 22.0.0 or higher node --version # Verify version # Clone the repository git clone https://github.com/RunMaestro/Maestro.git cd maestro # Install dependencies npm install # Run in development mode npm run dev # Or build for production npm run build npm run package ``` -------------------------------- ### Clone Project to Linux Filesystem (Bash) Source: https://docs.runmaestro.ai/troubleshooting Addresses 'npm install timeouts' or 'ENOTEMPTY' errors caused by unreliable cross-filesystem operations. This solution involves cloning the repository directly into the Linux filesystem and then running npm install. ```bash cd ~ git clone https://github.com/RunMaestro/Maestro.git cd maestro npm install ``` -------------------------------- ### SSH Config File Example Source: https://docs.runmaestro.ai/ssh-remote-execution An example of an SSH configuration file (`~/.ssh/config`) demonstrating how to define host patterns, hostnames, users, identity files, and ports. This file allows for simplified SSH command usage and is leveraged by Runmaestro AI in SSH config mode. ```sshconfig Host dev-server HostName 192.168.1.100 User developer IdentityFile ~/.ssh/dev_key Port 2222 Host gpu-box HostName gpu.example.com User admin IdentityFile ~/.ssh/gpu_key ProxyJump bastion ``` -------------------------------- ### Verify Agent CLI Installation (Bash) Source: https://docs.runmaestro.ai/ssh-remote-execution This command verifies that the AI agent CLI is installed and accessible on the remote host. It's a useful step to perform manually before configuring the agent in Maestro, ensuring basic connectivity and agent functionality. ```bash ssh host 'claude --version' ``` -------------------------------- ### Install Maestro CLI Wrapper Source: https://docs.runmaestro.ai/cli Shell script wrappers for the Maestro CLI tool, enabling execution via the 'maestro-cli' command. These scripts are tailored for macOS, Linux, and Windows installations, ensuring the Node.js CLI is correctly invoked. ```bash #!/bin/bash node "/Applications/Maestro.app/Contents/Resources/maestro-cli.js" "$@" ``` ```bash #!/bin/bash node "/opt/Maestro/resources/maestro-cli.js" "$@" ``` ```powershell @ @echo off node "%ProgramFiles%\Maestro\resources\maestro-cli.js" %* @ | Out-File -FilePath "$env:ProgramFiles\Maestro\maestro-cli.cmd" -Encoding ASCII ``` -------------------------------- ### Markdown Task Checkbox Example Source: https://docs.runmaestro.ai/autorun-playbooks Demonstrates how to create tasks within markdown documents using standard checkboxes. This format is recognized by Auto Run for task processing. ```markdown # Feature Implementation Plan - [ ] Implement user authentication - [ ] Add unit tests for the login flow - [ ] Update API documentation ``` -------------------------------- ### Run Maestro in Multiple Worktrees Simultaneously (Bash) Source: https://docs.runmaestro.ai/git-worktrees This snippet demonstrates how to run multiple instances of Maestro in different worktrees simultaneously using the VITE_PORT environment variable. It requires Node.js and npm to be installed. ```bash # In main worktree npm run dev # In worktree 2 (different terminal/directory) VITE_PORT=5174 npm run dev ``` -------------------------------- ### Scheduling Playbooks with Cron (Maestro CLI) Source: https://docs.runmaestro.ai/cli Provides an example of how to schedule a Maestro playbook to run at a specific interval using cron. It includes the --json flag for log parsing and redirects output to a log file for monitoring. ```bash 0 * * * * /usr/local/bin/maestro-cli playbook --json >> /var/log/maestro.jsonl 2>&1 ``` -------------------------------- ### SSH Configuration for Connection Multiplexing (SSH Config) Source: https://docs.runmaestro.ai/ssh-remote-execution This example SSH configuration enables connection multiplexing, which can improve performance and reduce latency, especially when using hardware security keys. It sets up automatic control master, defines a control path for sockets, and persists the connection. ```sshconfig Host dev-server ControlMaster auto ControlPath ~/.ssh/sockets/%r@%h-%p ControlPersist 600 ``` -------------------------------- ### Troubleshooting WSL2: Setting Temporary Directory Source: https://docs.runmaestro.ai/installation A command to set the temporary directory for npm operations, which can help resolve `electron-rebuild` failures in WSL2 environments. This is a common workaround for issues related to temporary file handling. ```bash TMPDIR=/tmp npm run rebuild ``` -------------------------------- ### Move Project to Linux Filesystem (Bash) Source: https://docs.runmaestro.ai/troubleshooting Resolves 'EPERM: operation not permitted' errors when Vite or Electron cannot bind to ports on Windows-mounted paths. This involves moving the project directory from `/mnt/...` to the Linux home directory (`~/...`) and reinstalling dependencies. ```bash mv /mnt/c/projects/maestro ~/maestro cd ~/maestro npm install npm run dev ``` -------------------------------- ### Create Symphony-Ready Issues (Markdown) Source: https://docs.runmaestro.ai/symphony This markdown format is used to create issues that are ready for Symphony contributions. It includes a title, description, and paths to Auto Run compatible markdown files for tasks. The `runmaestro.ai` label is required. ```markdown ```markdown theme={"theme":"dracula"} ## Add unit tests for auth module We need comprehensive test coverage for the authentication module. ### Auto Run Documents - `docs/symphony/auth-tests-1.md` - `docs/symphony/auth-tests-2.md` - `docs/symphony/auth-tests-3.md` ### Context The auth module is at `src/auth/index.ts`. Tests should use Jest. ``` ``` -------------------------------- ### Maestro Agent Message Response (Failure) Source: https://docs.runmaestro.ai/cli Example of a failed JSON response from the Maestro CLI. Indicates an error occurred during message processing, providing an error message and a specific error code. ```json { "success": false, "error": "Agent not found: bad-id", "code": "AGENT_NOT_FOUND" } ```