agentmux 1.0.0

Canonical configuration manager for AI coding agent components

agentmux

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	✓	✓	✓	✓	✓	✓
Gemini CLI	✓	✓	✓	✓	✓	✓
OpenCode	✓	✓	✓	✓	✓	✓
Claude Code	✓	✓	✓	✓	✓	✓

Installation

pip install agentmux

Or via Homebrew (using the agentmux tap):

brew install Omer-Sadeh/agentmux/agentmux

Quickstart

# 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)

[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)

---
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:

# 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:

[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.

License

MIT — see LICENSE.