### Full Project Build Command

Source: https://github.com/its-maestro-baby/maestro/blob/main/AGENTS.md

Executes frontend dependency installation, backend server build, and starts the Tauri app in dev mode.

```bash
npm install
cargo build --release -p maestro-mcp-server
npm run tauri dev
```

--------------------------------

### Install OpenCode CLI Hint

Source: https://github.com/its-maestro-baby/maestro/blob/main/docs/specs/opencode-support-brd.md

Display this message when the OpenCode CLI is not detected and guide the user on how to install it.

```bash
npm install -g opencode
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/its-maestro-baby/maestro/blob/main/AGENTS.md

Installs all necessary packages for the frontend development environment.

```bash
npm install
```

--------------------------------

### Install Linux Prerequisites on Ubuntu/Debian

Source: https://github.com/its-maestro-baby/maestro/blob/main/website/installation.md

Installs necessary development packages for Ubuntu/Debian-based Linux distributions.

```bash
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev \
  libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf
```

--------------------------------

### Copy MCP Configuration Example

Source: https://github.com/its-maestro-baby/maestro/blob/main/website/configuration.md

Use this command to copy the example MCP configuration file to your project. You will then edit this file to set the correct path to the MCP server binary.

```bash
cp .mcp.json.example .mcp.json
```

--------------------------------

### Start Frontend Development Server

Source: https://github.com/its-maestro-baby/maestro/blob/main/AGENTS.md

Launches the Vite development server for live frontend development.

```bash
npm run dev
```

--------------------------------

### Install Rust on Linux via rustup

Source: https://github.com/its-maestro-baby/maestro/blob/main/README.md

Installs Rust using rustup, which is recommended over system package managers for newer versions. Ensure to source the environment variables after installation.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
```

--------------------------------

### Install AI CLIs

Source: https://github.com/its-maestro-baby/maestro/blob/main/docs/issues/opencode-support-04-documentation.md

Provides installation commands for various AI CLIs, including OpenCode. Ensure OpenCode is installed globally using npm.

```bash
# Claude Code (recommended)
npm install -g @anthropic-ai/claude-code

# Gemini CLI
npm install -g @google/gemini-cli

# OpenAI Codex
npm install -g codex

# OpenCode
npm install -g opencode-ai
```

--------------------------------

### Install Required System Dependencies on Fedora

Source: https://github.com/its-maestro-baby/maestro/blob/main/README.md

Installs necessary development packages for building on Fedora.

```bash
sudo dnf install gcc-c++ pkg-config openssl-devel \
  webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel
```

--------------------------------

### Install Xcode Command Line Tools on macOS

Source: https://github.com/its-maestro-baby/maestro/blob/main/README.md

Run this command to install the necessary Xcode command line tools on macOS.

```bash
xcode-select --install
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/its-maestro-baby/maestro/blob/main/website/contributing.md

Clone the Maestro repository and install necessary npm dependencies to set up your development environment.

```bash
git clone https://github.com/YOUR-USERNAME/maestro.git
cd maestro
npm install
```

--------------------------------

### Clone Maestro Repository

Source: https://github.com/its-maestro-baby/maestro/blob/main/README.md

Clone the Maestro repository and navigate into the project directory to begin setup.

```bash
git clone https://github.com/its-maestro-baby/maestro.git
cd maestro
```

--------------------------------

### Install Required System Dependencies on Ubuntu

Source: https://github.com/its-maestro-baby/maestro/blob/main/README.md

Installs essential build tools and libraries required for building from source on Ubuntu 24.04 LTS. Note the use of `libayatana-appindicator3-dev` to avoid conflicts.

```bash
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev \
  libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev \
  libfontconfig1-dev patchelf
```

--------------------------------

### Install AI CLIs

Source: https://github.com/its-maestro-baby/maestro/blob/main/README.md

Install optional AI command-line interface tools globally. Claude Code is recommended.

```bash
# Claude Code (recommended)
npm install -g @anthropic-ai/claude-code

# Gemini CLI
npm install -g @google/gemini-cli

# OpenAI Codex
npm install -g @openai/codex
```

--------------------------------

### Install Required System Dependencies on Arch Linux

Source: https://github.com/its-maestro-baby/maestro/blob/main/README.md

Installs required packages for building on Arch Linux.

```bash
sudo pacman -S base-devel pkgconf openssl \
  webkit2gtk-4.1 libappindicator-gtk3 librsvg
```

--------------------------------

### Verify Claude CLI Installation

Source: https://github.com/its-maestro-baby/maestro/blob/main/README.md

Ensure the Claude CLI is installed globally and accessible in your system's PATH.

```bash
npm install -g @anthropic-ai/claude-code
which claude  # Should show the path
```

--------------------------------

### Troubleshoot OpenCode Not Found

Source: https://github.com/its-maestro-baby/maestro/blob/main/docs/issues/opencode-support-04-documentation.md

Instructions for resolving 'OpenCode Not Found' errors. This involves verifying global installation and PATH configuration.

```bash
npm install -g opencode-ai
which opencode  # Should show the path
```

--------------------------------

### OpenCode Not Installed Error Message

Source: https://github.com/its-maestro-baby/maestro/blob/main/docs/specs/opencode-support-brd.md

This error message is displayed when the OpenCode CLI is not found, providing instructions for installation.

```text
OpenCode CLI not found. Install with: npm install -g opencode
```

--------------------------------

### Run Tauri App in Development

Source: https://github.com/its-maestro-baby/maestro/blob/main/AGENTS.md

Starts the Tauri application in development mode, enabling hot-reloading and debugging.

```bash
npm run tauri dev
```

--------------------------------

### Manage Marketplace Plugins with Tauri

Source: https://context7.com/its-maestro-baby/maestro/llms.txt

Use `invoke` to load, add, refresh, and manage marketplace plugins. Install plugins globally or per-project, and enable/disable them for specific sessions.

```typescript
import { invoke } from "@tauri-apps/api/core";

// Load persisted marketplace data on startup
await invoke("load_marketplace_data");

// Add a marketplace source (e.g., a GitHub repository)
const source = await invoke("add_marketplace_source", {
  name: "Community Plugins",
  repositoryUrl: "https://github.com/myorg/maestro-plugins",
  isOfficial: false,
});

// Refresh all enabled sources (fetches plugins.json from each)
await invoke("refresh_all_marketplaces");

// Get available plugins from all enabled sources
const plugins = await invoke<{ 
  id: string;
  name: string;
  description: string;
  type: "skill" | "command" | "mcp";
  version: string;
  author: string;
  tags: string[];
}[]>("get_available_plugins");

// Install a plugin globally or scoped to a project
const installed = await invoke("install_marketplace_plugin", {
  marketplacePluginId: "plugin-uuid-from-source",
  scope: "global",             // "global" | "project"
  projectPath: null,           // required only for "project" scope
});

// Toggle a plugin on/off for a specific session
await invoke("set_marketplace_plugin_enabled", {
  projectPath: "/home/user/myproject",
  sessionId: 42,
  installedPluginId: installed.id,
  enabled: true,
});

// Uninstall a plugin
await invoke("uninstall_plugin", { installedPluginId: installed.id });
```

--------------------------------

### OpenCode Launch Failed Error Message

Source: https://github.com/its-maestro-baby/maestro/blob/main/docs/specs/opencode-support-brd.md

This error message is displayed when there is a failure to start an OpenCode session, including details about the error.

```text
Failed to start OpenCode: {error details}
```

--------------------------------

### Preview Production Frontend Build

Source: https://github.com/its-maestro-baby/maestro/blob/main/AGENTS.md

Serves the production build of the frontend locally for previewing.

```bash
npm run preview
```

--------------------------------

### Build and Run MCP Server in Development

Source: https://github.com/its-maestro-baby/maestro/blob/main/website/contributing.md

Build the MCP server using Cargo and run the application in development mode with Tauri.

```bash
cargo build --release -p maestro-mcp-server
npm run tauri dev
```

--------------------------------

### Build Rust Backend Server

Source: https://github.com/its-maestro-baby/maestro/blob/main/AGENTS.md

Compiles the Maestro MCP server in release mode using Cargo.

```bash
cargo build --release -p maestro-mcp-server
```

--------------------------------

### Build Frontend for Production

Source: https://github.com/its-maestro-baby/maestro/blob/main/AGENTS.md

Compiles TypeScript and builds the frontend application for production deployment using Vite.

```bash
npm run build
```

--------------------------------

### Create Feature Branch

Source: https://github.com/its-maestro-baby/maestro/blob/main/website/contributing.md

Create a new feature branch from the main branch to start working on your contribution.

```bash
git checkout -b feature/my-feature
```

--------------------------------

### Run Frontend Tests with Verbose Output

Source: https://github.com/its-maestro-baby/maestro/blob/main/AGENTS.md

Executes Vitest tests and displays detailed output for each test.

```bash
npx vitest run --reporter=verbose
```

--------------------------------

### Plugin Marketplace Management

Source: https://context7.com/its-maestro-baby/maestro/llms.txt

Functions for managing marketplace plugins, including adding sources, refreshing, installing, enabling, and uninstalling.

```APIDOC
## Marketplace Commands

### `install_marketplace_plugin` / `refresh_all_marketplaces` — Plugin marketplace

Browse and install Claude Code skills, commands, and MCP servers from remote marketplace sources.

### `load_marketplace_data`

**Description**: Loads persisted marketplace data on startup.

**Method**: `invoke` (Tauri API)

### `add_marketplace_source`

**Description**: Adds a marketplace source, such as a GitHub repository.

**Method**: `invoke` (Tauri API)

**Parameters**:
- `name` (string) - Required - The name of the marketplace source.
- `repositoryUrl` (string) - Required - The URL of the repository.
- `isOfficial` (boolean) - Required - Indicates if the source is official.

### `refresh_all_marketplaces`

**Description**: Refreshes all enabled marketplace sources, fetching the latest plugin information.

**Method**: `invoke` (Tauri API)

### `get_available_plugins`

**Description**: Retrieves a list of available plugins from all enabled marketplace sources.

**Method**: `invoke` (Tauri API)

**Returns**: An array of plugin objects, each with `id`, `name`, `description`, `type`, `version`, `author`, and `tags`.

### `install_marketplace_plugin`

**Description**: Installs a plugin from the marketplace, either globally or scoped to a project.

**Method**: `invoke` (Tauri API)

**Parameters**:
- `marketplacePluginId` (string) - Required - The ID of the plugin to install.
- `scope` (string) - Required - The scope of the installation (`"global"` or `"project"`).
- `projectPath` (string | null) - Optional - The project path, required only when `scope` is `"project"`.

### `set_marketplace_plugin_enabled`

**Description**: Toggles a plugin's enabled state for a specific session.

**Method**: `invoke` (Tauri API)

**Parameters**:
- `projectPath` (string) - Required - The path to the project.
- `sessionId` (number) - Required - The ID of the session.
- `installedPluginId` (string) - Required - The ID of the installed plugin.
- `enabled` (boolean) - Required - Whether to enable or disable the plugin.

### `uninstall_plugin`

**Description**: Uninstalls a plugin.

**Method**: `invoke` (Tauri API)

**Parameters**:
- `installedPluginId` (string) - Required - The ID of the installed plugin to uninstall.
```

--------------------------------

### Run All Frontend Tests Once

Source: https://github.com/its-maestro-baby/maestro/blob/main/AGENTS.md

Executes all Vitest tests in the project once.

```bash
npm run test
```

--------------------------------

### Define OpenCode AI Mode Type

Source: https://github.com/its-maestro-baby/maestro/blob/main/docs/specs/opencode-support-brd.md

Defines the TypeScript type for OpenCode within the AI mode configuration. Used for CLI commands and installation hints.

```typescript
export type AiMode = "Claude" | "Gemini" | "Codex" | "OpenCode" | "Plain";

export const AI_CLI_CONFIG: Record<AiMode, {
  command: string | null;
  installHint: string;
  skipPermissionsFlag: string | null;
}> = {
  // ... existing modes
  OpenCode: {
    command: "opencode",
    installHint: "npm install -g opencode",
    skipPermissionsFlag: "--dangerously-skip-permissions",  
  },
  // ...
};
```

--------------------------------

### Check MCP Server Binary

Source: https://github.com/its-maestro-baby/maestro/blob/main/website/troubleshooting.md

Verify the existence of the MCP server binary in the target release directory. Rebuild if missing.

```bash
ls src-tauri/target/release/maestro-mcp-server
```

--------------------------------

### Check for and Download App Updates

Source: https://context7.com/its-maestro-baby/maestro/llms.txt

Checks for app updates via the Tauri updater, optionally against a custom endpoint. Listens for download progress events and initiates download, installation, and restart.

```typescript
import { invoke } from "@tauri-apps/api/core";
import { listen } from "@tauri-apps/api/event";

// Check for updates (optionally against a custom endpoint)
const info = await invoke<{ 
  available: boolean;
  currentVersion: string;
  latestVersion: string;
  releaseNotes: string | null;
  date: string | null;
}>("check_for_updates", { customEndpoint: null });

if (info.available) {
  console.log(`Update available: ${info.currentVersion} → ${info.latestVersion}`);

  // Listen for download progress
  const unlisten = await listen<{ chunkLength: number; contentLength: number | null }>
    ("update-download-progress", (
      event
    ) => {
      const { chunkLength, contentLength } = event.payload;
      if (contentLength) {
        console.log(`Downloaded: ${chunkLength}/${contentLength} bytes`);
      }
    }
  );

  // Download, install, and restart (kills all PTY sessions first)
  await invoke("download_and_install_update", { customEndpoint: null });
  unlisten();
}

// Get current app version
const version = await invoke<string>("get_app_version");
// => "0.2.5"
```

--------------------------------

### Format Frontend Code with Biome

Source: https://github.com/its-maestro-baby/maestro/blob/main/AGENTS.md

Runs Biome to format the project's TypeScript/React code according to configured style rules.

```bash
npx @biomejs/biome format .
```

--------------------------------

### Build Production Tauri App

Source: https://github.com/its-maestro-baby/maestro/blob/main/AGENTS.md

Compiles the Tauri application into a production-ready executable.

```bash
npm run tauri build
```

--------------------------------

### check_cli_available

Source: https://context7.com/its-maestro-baby/maestro/llms.txt

Checks if a specified command-line interface (CLI) tool is available in the user's system PATH. This is useful for verifying the installation of AI tools like Claude, Gemini, or Codex.

```APIDOC
## check_cli_available

### Description
Checks if a command (e.g., `claude`, `gemini`, `codex`) is available in the user's PATH. Uses direct filesystem lookup on Unix to avoid hanging shell plugins like oh-my-zsh.

### Parameters
- **command** (string) - Required - The name of the command to check for (e.g., "claude").

### Response
#### Success Response (200)
- **isAvailable** (boolean) - `true` if the command is found in the PATH, `false` otherwise.

### Example Usage
```typescript
import { invoke } from "@tauri-apps/api/core";

const isInstalled = await invoke<boolean>("check_cli_available", {
  command: "claude",
});

if (!isInstalled) {
  console.warn("Claude CLI not found. Install with: npm install -g @anthropic-ai/claude-code");
}

// Check all supported AI CLIs
const modes = ["claude", "gemini", "codex", "opencode"];
const availability = await Promise.all(
  modes.map((cmd) => invoke<boolean>("check_cli_available", { command: cmd }))
);
```
```

--------------------------------

### Invoke Open Project Action (Frontend)

Source: https://github.com/its-maestro-baby/maestro/blob/main/docs/research/00-MASTER-ARCHITECTURAL-PLAN.md

Frontend code to invoke the 'open_project' action, passing the project path.

```javascript
invoke('open_project', { path })
```

--------------------------------

### MCP Status Schema Example

Source: https://github.com/its-maestro-baby/maestro/blob/main/website/configuration.md

This JSON structure defines the schema for AI agents reporting their status to the MCP server. It includes fields for agent ID, state, message, and timestamp.

```json
{
  "agentId": "agent-1",
  "state": "working",
  "message": "Implementing authentication module",
  "needsInputPrompt": null,
  "timestamp": "2026-01-30T20:14:15.123Z"
}
```

--------------------------------

### Configure OpenCode CLI in terminal.ts

Source: https://github.com/its-maestro-baby/maestro/blob/main/docs/issues/opencode-support-01-mode-selection.md

Define the command, install hint, and skip permissions flag for OpenCode within the `AI_CLI_CONFIG` in `src/lib/terminal.ts`. This configuration is used for CLI availability checks and user guidance.

```typescript
export type AiMode = "Claude" | "Gemini" | "Codex" | "OpenCode" | "Plain";

export const AI_CLI_CONFIG: Record<AiMode, {
  command: string | null;
  installHint: string;
  skipPermissionsFlag: string | null;
}> = {
  // ... existing modes
  OpenCode: {
    command: "opencode",
    installHint: "npm install -g opencode-ai",
    skipPermissionsFlag: "--dangerously-skip-permissions",
  },
  // ...
};
```

--------------------------------

### Run Specific Frontend Test File

Source: https://github.com/its-maestro-baby/maestro/blob/main/AGENTS.md

Executes a single Vitest test file, specifying its path.

```bash
npx vitest run src/components/path/Component.test.tsx
```

--------------------------------

### Check for External Drive Path

Source: https://github.com/its-maestro-baby/maestro/blob/main/docs/issues/macos-volume-access-fix.md

This TypeScript code snippet checks if a given path starts with '/Volumes/'. If it does, it returns false, indicating that external drives bypass certain permission checks in the current implementation.

```typescript
export function pathRequiresFDA(path: string): boolean {
  if (path.startsWith("/Volumes/")) {
    return false;  // <-- External drives bypass ALL permission checks
  }
  // ... only checks ~/Desktop, ~/Documents, ~/Downloads
}
```

--------------------------------

### Add OpenCode to Multi-AI Support List

Source: https://github.com/its-maestro-baby/maestro/blob/main/docs/issues/opencode-support-04-documentation.md

Update the README.md to include OpenCode in the list of supported AI assistants. Ensure the correct URL is provided.

```markdown
### Multi-AI Support
- **Claude Code** - Anthropic's Claude in the terminal
- **Gemini CLI** - Google's Gemini AI
- **OpenAI Codex** - OpenAI's coding assistant
- **OpenCode** - AI coding assistant (https://opencode.ai)
- **Plain Terminal** - Standard shell without AI
```

--------------------------------

### Get Terminal Backend Capabilities

Source: https://context7.com/its-maestro-baby/maestro/llms.txt

Queries the active terminal backend for its type and supported features like enhanced state, text reflow, and Kitty graphics. This information is used to conditionally enable or disable UI features based on the terminal's capabilities.

```typescript
import { invoke } from "@tauri-apps/api/core";

const info = await invoke<{
  backendType: "XtermPassthrough" | "VteParser";
  capabilities: {
    enhancedState: boolean;
    textReflow: boolean;
    kittyGraphics: boolean;
    shellIntegration: boolean;
    backendName: string;
  };
}>("get_backend_info");

// Expected output on macOS/Windows (xterm passthrough):
// { backendType: "XtermPassthrough", capabilities: { enhancedState: false, ... } }
// On Linux with VTE:
// { backendType: "VteParser", capabilities: { enhancedState: true, ... } }
```

--------------------------------

### Check AI CLI Availability

Source: https://context7.com/its-maestro-baby/maestro/llms.txt

Checks if a specified AI command-line interface (CLI) is available in the user's PATH. Uses direct filesystem lookup on Unix to avoid potential hangs with shell plugins. This is useful for ensuring necessary tools are installed before attempting to use them.

```typescript
import { invoke } from "@tauri-apps/api/core";

const isInstalled = await invoke<boolean>("check_cli_available", {
  command: "claude",
});

if (!isInstalled) {
  console.warn("Claude CLI not found. Install with: npm install -g @anthropic-ai/claude-code");
}

// Check all supported AI CLIs
const modes = ["claude", "gemini", "codex", "opencode"];
const availability = await Promise.all(
  modes.map((cmd) => invoke<boolean>("check_cli_available", { command: cmd }))
);
```

--------------------------------

### Invoke Create Session Action (Frontend)

Source: https://github.com/its-maestro-baby/maestro/blob/main/docs/research/00-MASTER-ARCHITECTURAL-PLAN.md

Frontend code to invoke the 'create_session' action, specifying project ID, mode, and branch.

```javascript
invoke('create_session', { projectId, mode: 'claude', branch: 'feature/login' })
```

--------------------------------

### Manage CLAUDE.md Project Instructions File

Source: https://context7.com/its-maestro-baby/maestro/llms.txt

Manages the CLAUDE.md file at the project root, which contains natural-language instructions for Claude Code. This includes checking for existence, reading content, and writing/updating the file.

```typescript
import { invoke } from "@tauri-apps/api/core";

// Check if CLAUDE.md exists and optionally read its content
const status = await invoke<{ 
  exists: boolean;
  path: string;
  content: string | null;
}>("check_claude_md", { projectPath: "/home/user/myproject" });

if (!status.exists) {
  // Create a new CLAUDE.md
  await invoke("write_claude_md", {
    projectPath: "/home/user/myproject",
    content: "# Project Guidelines\n\n## Stack\n- TypeScript, React, Tailwind CSS\n\n## Conventions\n- Use functional components with hooks\n- All API calls go through src/lib/",
  });
}

// Read and edit
const content = await invoke<string>("read_claude_md", {
  projectPath: "/home/user/myproject",
});
const updated = content + "\n## New Rule\n- Always write tests.";
await invoke("write_claude_md", {
  projectPath: "/home/user/myproject",
  content: updated,
});
```

--------------------------------

### Spawn Shell and Listen for PTY Output

Source: https://context7.com/its-maestro-baby/maestro/llms.txt

Spawns a new shell process in a pseudo-terminal with custom environment variables. It also demonstrates how to listen for PTY output and send commands to the session.

```typescript
import { invoke } from "@tauri-apps/api/core";
import { listen } from "@tauri-apps/api/event";

// Spawn a shell in a worktree directory with custom environment
const sessionId = await invoke<number>("spawn_shell", {
  cwd: "/home/user/myproject/.claude-maestro/worktrees/abc123/feature-auth",
  env: {
    MAESTRO_PROJECT_HASH: "abc123def456",
    CLAUDE_SKIP_PERMISSIONS: "1",
  },
});

// Subscribe to PTY output
const unlisten = await listen<string>(`pty-output-${sessionId}`, (event) => {
  terminal.write(event.payload); // Write to xterm.js instance
});

// Send a CLI command to the session
await invoke("write_stdin", { sessionId, data: "claude --resume\r" });

// Resize the terminal
await invoke("resize_pty", { sessionId, rows: 40, cols: 120 });

// Kill when done (SIGTERM then SIGKILL after 3s)
await invoke("kill_session", { sessionId });
unlisten();
```