PHPackages                             myleshyson/mush - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. myleshyson/mush

ActiveLibrary[Utility & Helpers](/categories/utility)

myleshyson/mush
===============

A simple tool to manage AI guideline configurations

v0.3.0(5mo ago)010MITPHPPHP ^8.2CI passing

Since Jan 19Pushed 5mo agoCompare

[ Source](https://github.com/myleshyson/mush)[ Packagist](https://packagist.org/packages/myleshyson/mush)[ RSS](/packages/myleshyson-mush/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (10)Versions (13)Used By (0)

```
 ▄▄       ▄▄  ▄         ▄  ▄▄▄▄▄▄▄▄▄▄▄  ▄         ▄
▐░░▌     ▐░░▌▐░▌       ▐░▌▐░░░░░░░░░░░▌▐░▌       ▐░▌
▐░▌░▌   ▐░▐░▌▐░▌       ▐░▌▐░█▀▀▀▀▀▀▀▀▀ ▐░▌       ▐░▌
▐░▌▐░▌ ▐░▌▐░▌▐░▌       ▐░▌▐░▌          ▐░▌       ▐░▌
▐░▌ ▐░▐░▌ ▐░▌▐░▌       ▐░▌▐░█▄▄▄▄▄▄▄▄▄ ▐░█▄▄▄▄▄▄▄█░▌
▐░▌  ▐░▌  ▐░▌▐░▌       ▐░▌▐░░░░░░░░░░░▌▐░░░░░░░░░░░▌
▐░▌   ▀   ▐░▌▐░▌       ▐░▌ ▀▀▀▀▀▀▀▀▀█░▌▐░█▀▀▀▀▀▀▀█░▌
▐░▌       ▐░▌▐░▌       ▐░▌          ▐░▌▐░▌       ▐░▌
▐░▌       ▐░▌▐░█▄▄▄▄▄▄▄█░▌ ▄▄▄▄▄▄▄▄▄█░▌▐░▌       ▐░▌
▐░▌       ▐░▌▐░░░░░░░░░░░▌▐░░░░░░░░░░░▌▐░▌       ▐░▌
 ▀         ▀  ▀▀▀▀▀▀▀▀▀▀▀  ▀▀▀▀▀▀▀▀▀▀▀  ▀         ▀

```

A CLI tool that syncs AI agent configurations across your team. Define guidelines, skills, custom agents, slash commands, and MCP servers once in `.mush/` and automatically sync them to Claude Code, Cursor, Copilot, Gemini, OpenCode, Codex, and Junie.

Installation
------------

[](#installation)

### Quick Install (Recommended)

[](#quick-install-recommended)

```
curl -fsSL https://raw.githubusercontent.com/myleshyson/mush/main/install.sh | sh
```

### Custom Install Location

[](#custom-install-location)

```
curl -fsSL https://raw.githubusercontent.com/myleshyson/mush/main/install.sh | MUSH_INSTALL_DIR=~/.local/bin sh
```

### Install Specific Version

[](#install-specific-version)

```
curl -fsSL https://raw.githubusercontent.com/myleshyson/mush/main/install.sh | MUSH_VERSION=v1.0.0 sh
```

### Manual Download

[](#manual-download)

Download the appropriate binary for your platform from the [releases page](https://github.com/myleshyson/mush/releases):

- `mush-linux-x86_64` - Linux (Intel/AMD)
- `mush-linux-aarch64` - Linux (ARM64)
- `mush-macos-x86_64` - macOS (Intel)
- `mush-macos-aarch64` - macOS (Apple Silicon)
- `mush-windows-x64.exe` - Windows (64-bit)

### Install via Composer (PHP 8.2+)

[](#install-via-composer-php-82)

If you have PHP and Composer installed:

```
composer global require myleshyson/mush
```

Or add as a dev dependency to your project:

```
composer require --dev myleshyson/mush
./vendor/bin/mush install
```

Getting Started
---------------

[](#getting-started)

### Initialize a New Project

[](#initialize-a-new-project)

```
# Interactive mode - select which agents to configure
mush install

# Or specify agents directly
mush install --claude --cursor --copilot
```

This creates a `.mush/` directory with:

```
.mush/
├── guidelines/     # Shared guidelines (markdown files)
├── skills/         # Reusable skills (subdirectories with SKILL.md)
├── agents/         # Custom agents (markdown files)
├── commands/       # Slash commands (markdown files)
└── mcp.json        # MCP server configurations

```

### Update Agent Files

[](#update-agent-files)

After modifying your `.mush/` configuration, sync changes to all detected agents:

```
mush update
```

Mush automatically detects which agents are configured in your project and updates their respective files.

Configuration
-------------

[](#configuration)

### Guidelines

[](#guidelines)

Add markdown files to `.mush/guidelines/` to define shared instructions:

```

# Code Style

- Use consistent indentation (4 spaces)
- Write descriptive variable names
- Add comments for complex logic
```

Guidelines are compiled alphabetically, so prefix filenames with numbers to control order:

- `01-overview.md`
- `02-code-style.md`
- `03-testing.md`

### Skills

[](#skills)

Skills are reusable instruction sets that agents can invoke. Create a subdirectory in `.mush/skills/` with a`SKILL.md`file:

```

---
name: testing
description: Helps write and run tests for the codebase
---

# Testing Guidelines

When writing tests:

- Use descriptive test names
- Follow AAA pattern (Arrange, Act, Assert)
- Mock external dependencies
```

The `description` field helps agents decide when to apply the skill.

### MCP Servers

[](#mcp-servers)

Configure MCP (Model Context Protocol) servers in `.mush/mcp.json`:

```
{
  "servers": {
    "database": {
      "command": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "DATABASE_URL": "postgres://localhost/mydb"
      }
    },
    "github": {
      "command": [
        "npx",
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}
```

Mush transforms this configuration to each agent's expected format.

### Custom Agents

[](#custom-agents)

Custom agents are specialized personas that can be invoked during conversations. Create markdown files in `.mush/agents/`:

```

---
name: security-reviewer
description: Reviews code for security vulnerabilities and best practices
---

# Security Reviewer

You are a security expert. When reviewing code:

- Check for injection vulnerabilities (SQL, XSS, command injection)
- Verify authentication and authorization logic
- Look for sensitive data exposure
- Ensure proper input validation
```

The `name` field is the identifier used to invoke the agent, and `description` helps users understand when to use it.

### Slash Commands

[](#slash-commands)

Slash commands are reusable prompts that can be invoked with a `/` prefix. Create markdown files in `.mush/commands/`:

```

---
name: review
description: Review code for quality and best practices
---

Please review the selected code for:

1. Code quality and readability
2. Potential bugs or edge cases
3. Performance considerations
4. Adherence to project conventions
```

Commands provide a quick way to run common prompts without retyping them.

### Local Overrides

[](#local-overrides)

For personal MCP servers that shouldn't be committed (local databases, personal API tokens), create `.mush/mcp.override.json`:

```
{
  "servers": {
    "github": {
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "my-personal-token"
      }
    },
    "local-db": {
      "command": ["npx", "-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgres://localhost/mydevdb"
      }
    }
  }
}
```

Override servers completely replace matching servers from `mcp.json`. This file is automatically added to `.gitignore` during `mush install`.

For personal guidelines or skills that shouldn't be shared, add them to `.mush/` and gitignore them. Use the `!` prefix to explicitly track shared files:

```
# Ignore all mush config by default
.mush/guidelines/*
.mush/skills/*

# Track shared files
!.mush/guidelines/code-style.md
!.mush/guidelines/testing.md
!.mush/skills/api-design/
```

Commands
--------

[](#commands)

### `mush install`

[](#mush-install)

Initialize Mush in a project.

```
# Interactive mode
mush install

# Specify agents
mush install --claude --cursor --copilot --gemini --opencode --codex --junie

# All agents
mush install --claude --cursor --copilot --gemini --opencode --codex --junie
```

### `mush update`

[](#mush-update)

Sync `.mush/` configuration to all detected agents.

```
# Auto-detect agents
mush update

# Custom paths for additional outputs
mush update --guideline-path=./custom/RULES.md
mush update --skill-path=./custom/skills/
mush update --mcp-path=./custom/mcp.json
mush update --agents-path=./custom/agents/
mush update --commands-path=./custom/commands/
```

Supported Agents
----------------

[](#supported-agents)

AgentGuidelinesSkillsMCPAgentsCommandsClaude Code`.claude/CLAUDE.md``.claude/skills/``.claude/mcp.json``.claude/agents/``.claude/commands/`Cursor`.cursor/rules/mush.mdc``.cursor/skills/``.cursor/mcp.json`—`.cursor/commands/`GitHub Copilot`.github/copilot-instructions.md``.github/skills/``.vscode/mcp.json``.github/agents/``.github/prompts/`\*\*Gemini`GEMINI.md``.gemini/skills/``.gemini/settings.json`—`.gemini/commands/`\*\*\*OpenCode`AGENTS.md``.opencode/skills/``opencode.json``.opencode/agents/``.opencode/commands/`OpenAI Codex`AGENTS.md``.codex/skills/`—\*——Junie`.junie/guidelines.md``.junie/skills/``.junie/mcp/mcp.json`—`.junie/commands/`\*OpenAI Codex supports MCP via `~/.codex/config.toml`, but only at the global/user level, not per-project. Mush focuses on project-level configuration, so Codex MCP is not currently supported.

\*\*GitHub Copilot uses `.prompt.md` extension for commands.

\*\*\*Gemini uses TOML format for commands.

Example Workflow
----------------

[](#example-workflow)

1. **Initialize Mush**

    ```
    cd my-project
    mush install --claude --cursor
    ```
2. **Add guidelines**

    ```
    echo "# Always use TypeScript" > .mush/guidelines/typescript.md
    ```
3. **Add a skill**

    ```
    mkdir -p .mush/skills/api-design
    cat > .mush/skills/api-design/SKILL.md