Maestro

https://docs.runmaestro.ai
Admin
Maestro is a cross-platform desktop app for orchestrating multiple AI coding agents with a...
Tokens:42,048
Snippets:275
Trust Score:4.8
Update:7 months ago
Show doc for...
Tokens:
Raw
### 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 <playbook-id> --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"
}

```
Tokens:
Raw