# agentmux

[![PyPI version](https://img.shields.io/pypi/v/agentmux.svg)](https://pypi.org/project/agentmux/)
[![Python versions](https://img.shields.io/pypi/pyversions/agentmux.svg)](https://pypi.org/project/agentmux/)
[![CI](https://github.com/Omer-Sadeh/agentmux/actions/workflows/ci.yml/badge.svg)](https://github.com/Omer-Sadeh/agentmux/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**agentmux** is a CLI tool that manages AI coding agent configurations — agents, commands, skills, rules, instructions, and MCP servers — from a single canonical format (Markdown + YAML frontmatter) and syncs them across all your AI tools at once.

Write your agent configurations once. Deploy everywhere.

## Supported Tools

| Tool | Agents | Commands | Skills | Rules | Instructions | MCP |
|------|:------:|:--------:|:------:|:-----:|:------------:|:---:|
| [Cursor](https://cursor.com) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| [OpenCode](https://opencode.ai) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

## Installation

```bash
pip install agentmux
```

Or via Homebrew (using the [agentmux tap](https://github.com/Omer-Sadeh/homebrew-agentmux)):

```bash
brew install Omer-Sadeh/agentmux/agentmux
```

## Quickstart

```bash
# 1. Initialize a new setup in your project directory
agentmux init

# 2. Create your first agent
agentmux new agent my-agent --description "My AI coding assistant"

# 3. Sync to all detected AI tools
agentmux sync

# 4. Check deployment status
agentmux status
```

## How It Works

agentmux reads component files (Markdown with YAML frontmatter) from your setup directory and deploys them to each configured AI tool's global config location. Deployments use symlinks by default, so edits to your source files are instantly reflected everywhere.

### Setup file (`agentmux.toml`)

```toml
[setup]
name = "my-setup"
version = "1.0.0"

[tools]
cursor = { enabled = true, strategy = "symlink" }
gemini = { enabled = true, strategy = "generate" }

[components]
agents      = ["agents/*.md"]
commands    = ["commands/*.md"]
skills      = ["skills/*/SKILL.md"]
rules       = ["rules/*.md"]
instructions = "instructions.md"
mcps        = "mcp.json"
```

### Agent file (`agents/my-agent.md`)

```markdown
---
name: My Agent
description: A helpful coding assistant
---

You are a helpful AI coding assistant. Your job is to...
```

## CLI Reference

| Command | Description |
|---------|-------------|
| `agentmux init` | Initialize a new setup in the current directory |
| `agentmux new <type> <name>` | Scaffold a new component (agent, command, skill, rule, mcp) |
| `agentmux sync` | Sync all components to configured tools |
| `agentmux sync --dry-run` | Preview what would be synced |
| `agentmux status` | Show deployment status across all tools |
| `agentmux validate` | Validate configuration and all components |
| `agentmux install <source>` | Install a setup from a git URL or local path |
| `agentmux update [name]` | Pull and redeploy the latest version of an installed setup |
| `agentmux uninstall <name>` | Remove an installed setup and its deployed files |
| `agentmux diff [name]` | Show what changed since last install/update |
| `agentmux list` | List all installed setups |
| `agentmux rollback [name]` | Restore files to before the last sync |
| `agentmux watch` | Auto-sync on file changes |
| `agentmux doctor` | Check which AI tools are installed |

## Sharing Setups

agentmux supports installing shared setups directly from git repositories:

```bash
# Install from GitHub
agentmux install https://github.com/user/my-agent-setup

# Preview before installing
agentmux install https://github.com/user/my-agent-setup --dry-run

# Keep it up to date
agentmux update my-agent-setup
```

## Plugin System

Third-party tool adapters can be registered via Python entry points:

```toml
[project.entry-points."agentmux.adapters"]
my-tool = "my_package.adapter:MyToolAdapter"
```

agentmux will discover and load any installed adapter automatically.

## Contributing

Contributions are welcome! Please open an issue or pull request on [GitHub](https://github.com/Omer-Sadeh/agentmux).

## License

MIT — see [LICENSE](LICENSE).
