pmx 0.1.0

A CLI tool for managing AI agent profiles across different platforms (Claude, Codex)
Documentation

PMX

Crates.io CI License: MIT

A simple CLI tool to manage and switch between AI agent profiles across different platforms.

What is PMX?

PMX helps you organize and quickly switch between different AI agent configurations. Instead of manually editing configuration files or copying profile text, PMX lets you store multiple profiles and apply them with a single command.

Think of it like switching between different "personas" or instruction sets for your AI agents - whether you're doing code reviews, writing documentation, or working on specific projects.

Why Use PMX?

  • Quick Profile Switching: Change your AI agent's behavior instantly
  • Multi-Platform: Works with Claude Code, OpenAI Codex, and more
  • Profile Library: Store and organize multiple profiles in one place
  • Easy Sharing: Copy profiles to clipboard for quick sharing
  • Zero Setup: Auto-discovers configuration directories

✨ Features

  • Profile Management: Create, edit, delete, and show profiles with full CRUD operations
  • Editor Integration: Edit profiles using your preferred $EDITOR
  • Append Mode: Add profiles to existing configurations without overwriting
  • Nested Organization: Organize profiles in directories for better structure
  • Smart Display: Tree-style output in terminal, simple list when piped
  • Clipboard Support: Copy profile contents directly to clipboard
  • Shell Completions: Tab completion for Zsh (more shells coming soon)
  • Configuration Control: Enable/disable specific agents via config.toml

🚀 Installation

From crates.io

Once published, you can install pmx directly from crates.io:

cargo install pmx

This will install the pmx binary to your Cargo bin directory (typically ~/.cargo/bin/). Make sure this directory is in your PATH.

Prerequisites: Rust and Cargo must be installed. You can install them from rustup.rs.

From Source

cargo install --path .

Or install to a specific location:

cargo install --path . --root ~/.local

Building from Source

cargo build --release

The binary will be available at target/release/pmx

📋 How to Use

Basic Workflow

  1. Store your profiles as .md files in ~/.config/pmx/repo/
  2. List available profiles to see what you have
  3. Apply a profile to your AI agent
  4. Reset when needed to clear the current profile

Commands

See what profiles you have:

pmx profile list

Apply a profile to Claude Code:

pmx set-claude-profile my-code-reviewer

Append to existing Claude profile:

pmx append-claude-profile additional-instructions

Apply a profile to OpenAI Codex:

pmx set-codex-profile my-documentation-writer

Append to existing Codex profile:

pmx append-codex-profile additional-context

Remove the current profile:

pmx reset-claude-profile
pmx reset-codex-profile

Profile Management Commands

Create a new profile:

pmx profile create my-new-profile

Edit an existing profile:

pmx profile edit my-profile

Show profile contents:

pmx profile show my-profile

Copy a profile to your clipboard:

pmx profile copy project-specific-instructions

Delete a profile (with confirmation):

pmx profile delete old-profile

Example Use Cases

Code Review Profile:

pmx set-claude-profile code-reviewer
# Now Claude will focus on security, performance, and best practices

Documentation Writer:

pmx set-claude-profile tech-writer
# Now Claude will write clear, user-friendly documentation

Project-Specific Instructions:

pmx set-claude-profile projects/startup
# Now Claude knows your company's coding standards and domain

Development Profiles in Nested Directories:

pmx set-claude-profile development/backend
# Apply backend-specific development guidelines

pmx append-claude-profile development/security
# Add security-focused instructions to existing profile

📁 Profile Organization

PMX stores profiles in ~/.config/pmx/repo/ as Markdown files. You can organize profiles in nested directories:

~/.config/pmx/
├── config.toml              # Settings
└── repo/                    # Your profiles
    ├── code-reviewer.md     # Focuses on code quality
    ├── tech-writer.md       # Great at documentation
    ├── development/         # Development profiles
    │   ├── backend.md       # Backend-specific instructions
    │   └── frontend.md      # Frontend guidelines
    └── projects/            # Project-specific profiles
        ├── startup.md       # Startup context
        └── enterprise.md    # Enterprise standards

Each profile is just a .md file containing the instructions you want your AI agent to follow. Use directories to organize related profiles together.

⚙️ Setup

PMX works out of the box! It automatically:

  • Creates the config directory at ~/.config/pmx/
  • Sets up the profile repository in repo/
  • Configures agent settings in config.toml

Custom Configuration Location

You can override the default configuration directory in two ways:

Using command-line option:

pmx --config /path/to/custom/config profile list

Using environment variable:

export PMX_CONFIG_FILE=/path/to/your/config
pmx profile list

The priority order is:

  1. --config command-line option
  2. $PMX_CONFIG_FILE environment variable
  3. $XDG_CONFIG_HOME/pmx (if XDG_CONFIG_HOME is set)
  4. ~/.config/pmx (default)

🔧 Shell Completions

Make typing commands faster with auto-completion:

# For Zsh
source <(pmx completion zsh)

📚 Documentation

Man pages are available in assets/manual/. To install:

# System-wide installation
sudo cp assets/manual/pmx.1 /usr/share/man/man1/

# User installation
mkdir -p ~/.local/share/man/man1
cp assets/manual/pmx.1 ~/.local/share/man/man1/

Then view with: man pmx

🏗️ How It Works

PMX is built in Rust with a modular architecture:

  • Storage System: Auto-discovers config directories and manages profiles
  • CLI Interface: Clean command parsing with clap
  • Agent Modules: Separate handlers for Claude Code (~/.claude/CLAUDE.md) and Codex (~/.codex/AGENTS.md)
  • Profile Management: Full CRUD operations with editor integration and clipboard support
  • Smart Output: Tree-style display in terminal, simple list when piped (using is-terminal)
  • Append Mode: Add profiles to existing configurations without overwriting
  • Interactive Features: Confirmation dialogs for destructive operations (using dialoguer)

The tool follows a configuration-first approach where agent support can be conditionally enabled/disabled via config.toml.

Key Dependencies

  • clap - Command-line argument parsing
  • anyhow - Error handling
  • serde/toml - Configuration management
  • arboard - Clipboard integration
  • dialoguer - Interactive prompts
  • is-terminal - Terminal detection for smart output
  • tempfile - Safe temporary file handling

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Test with cargo test
  4. Format with cargo fmt
  5. Submit a pull request