Installation

Installation

Prerequisites

• Python 3.9 or higher (for pip-based installs)
• No Python needed if you use a standalone binary

Install methods

PyPI (recommended)

# uv: install as a tool, or run it once with no install
uv tool install universal-ai-config
uvx ai-config --help

# pipx: isolated environment
pipx install universal-ai-config

# pip
pip install universal-ai-config

All of these install the ai-config command.

One-line installer

curl -fsSL https://raw.githubusercontent.com/DevArtsLab/tool-universal-ai-config/main/install.sh | bash

The installer prefers uv or pipx when available and falls back to a managed virtual environment. It will:

• Install the package and set up the ai-config command
• Detect and offer to migrate existing provider configurations
• Initialize the unified config structure
• Add ~/.local/bin to your PATH if needed

Standalone binaries

Prebuilt binaries are attached to each GitHub release:

• ai-config-linux-x86_64
• ai-config-macos-x86_64 (Intel)
• ai-config-macos-arm64 (Apple Silicon)
• ai-config-windows-x86_64.exe

Download, make executable (chmod +x), and put it on your PATH.

From source

git clone https://github.com/DevArtsLab/tool-universal-ai-config.git
cd tool-universal-ai-config
pip install -e .

For development with test/lint tooling:

pip install -e ".[dev]"

Verify the install

ai-config --help

You should see the help output listing all commands. See CLI Reference for details.

Platform notes

Platform	Config	Data	State	Cache
Linux / macOS	~/.agents/config/	~/.agents/data/	~/.agents/state/	~/.agents/cache/
Windows	%USERPROFILE%\.agents\config\	%USERPROFILE%\.agents\data\	%USERPROFILE%\.agents\state\	%USERPROFILE%\.agents\cache\

Every platform uses ~/.agents/; set AGENT_CONFIG_HOME to relocate the base directory.

Uninstall

curl -fsSL https://raw.githubusercontent.com/DevArtsLab/tool-universal-ai-config/main/uninstall.sh | bash

This removes venv, uv, and pipx installs. Config files under ~/.agents/ are preserved unless you pass --remove-config.

Or uninstall just the package:

pip uninstall universal-ai-config

Removing config files is a separate step:

rm -rf ~/.agents/config/ ~/.agents/data/ ~/.agents/state/ ~/.agents/cache/
rm -rf .ai/   # per project

Next steps

• New install: Quick Start
• Existing Devin/Windsurf/Claude configs: Migration
• Having trouble: Troubleshooting