Skip to main content

Universal AI Configuration

A unified configuration system for AI agents across multiple providers (Devin, Windsurf, Claude, etc.). This tool provides a single source of truth for AI agent settings, skills, MCP servers, and rules.

Features

  • Unified Configuration: Single config file for all AI providers
  • XDG-Compliant: Follows Linux/macOS/Windows directory standards
  • Migration Support: Automatically migrates existing provider configs
  • Sync: Writes unified config back to each provider's native files (ai-config sync)
  • Project-Local: Per-project configuration with .agents/ directory (legacy .ai/ still supported)
  • Shared Resources: MCP servers and skills shared across providers
  • Drift Detection: Skills lockfile tracks pushed content hashes, so locally edited or stale provider copies surface in status and are backed up rather than overwritten
  • Provider Overrides: Provider-specific settings when needed

Supported Providers

Provider Config MCP servers Rules Skills
Devin ~/.config/devin/config.json mcp_config.json AGENTS.md yes
Windsurf ~/.windsurf/config.json mcp_config.json global rules / .windsurf/rules/ yes
Claude ~/.claude/settings.json .mcp.json CLAUDE.md yes
Cursor ~/.cursor/settings.json ~/.cursor/mcp.json .cursor/rules/*.mdc yes
Codex CLI ~/.codex/config.toml same file (TOML) AGENTS.md -
Gemini CLI ~/.gemini/settings.json mcpServers key GEMINI.md -
VS Code / Copilot settings.json mcp.json (servers key) .github/copilot-instructions.md -
Zed ~/.config/zed/settings.json context_servers key .rules -
Continue ~/.continue/config.yaml mcpServers list .continue/rules/ -

Sync is opt-in: detection alone never pushes anything into a provider. A provider only receives writes when you set "providers.<name>.sync": true in ~/.agents/config/config.json, or when you pass --provider <name> / --all for an explicit one-off export.

Legacy paths are covered too: the Windsurf line spans Codeium-era (~/.codeium/) through current ~/.windsurf/ locations, and Devin detection covers both ~/.config/devin/ (active config) and ~/.devin/ (application data). Migration reads every known path; sync writes to the provider's current master location (Windsurf skills: ~/.codeium/windsurf/skills/).

Installation

# uv (or run without installing: uvx ai-config --help)
uv tool install universal-ai-config

# pipx
pipx install universal-ai-config

# pip
pip install universal-ai-config

One-Line Install

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 migrate existing configurations
  • Initialize the unified config structure

Standalone Binaries

Prebuilt binaries for Linux, macOS (Intel and Apple Silicon), and Windows are attached to each GitHub release

  • no Python required.

Manual Install

# Clone the repository
git clone https://github.com/DevArtsLab/tool-universal-ai-config.git
cd tool-universal-ai-config

# Install via pip
pip install -e .

Quick Start

New Users

Initialize a fresh configuration:

ai-config init

Initialize for a project:

cd your-project
ai-config init-project

Existing Users

Migrate from existing provider configurations:

ai-config migrate

Migrate project-specific configs:

cd your-project
ai-config migrate --project

Directory Structure

User-Global Configuration

~/.agents/                  # All agent data in one place
  ├── AGENTS.md           # Shared rules (global)
  ├── .ai-config-lock.json # Skills lockfile: hashes, origins, sync receipts
  ├── skill-conflicts/    # Quarantined same-name skills pending resolution
  ├── config/
  │   ├── config.json     # Unified config (all providers read this)
  │   └── mcp-config.json # MCP servers
  ├── skills/             # Shared skills
  │   └── example-skill/
  ├── data/               # Long-term memory, datasets, plugins
  │   ├── memory/
  │   └── plugins/
  ├── state/              # Logs, history, active sessions
  │   ├── logs/
  │   └── history/
  └── cache/              # Model caches, isolated environments
      ├── models/
      └── venv/

Project-Local Configuration

.agents/                  # In repository root (.ai/ also recognized)
  ├── config.json         # Shared team settings
  ├── config.local.json   # Personal overrides (gitignored)
  ├── skills/             # Project-specific skills
  ├── mcp-config.json     # Project MCP servers
  ├── mcp-config.local.json # Project MCP overrides (gitignored)
  └── AGENTS.md           # Project rules

Configuration Format

Unified Config (~/.agents/config/config.json)

{
  "shared": {
    "permissions": {
      "allow": ["Read(**)", "Exec(git)"],
      "deny": ["Exec(sudo)"],
      "ask": ["Write(**/.env*)"]
    }
  },
  "providers": {
    "devin": {
      "permissions": {
        "allow": ["Read(**)", "Exec(git)", "Exec(npm)"]
      }
    }
  },
  "skills": {
    "enabled": [],
    "paths": ["~/.agents/skills/", ".agents/skills/", ".ai/skills/"]
  }
}

MCP Config (~/.agents/config/mcp-config.json)

MCP servers are kept in a separate file under the context_servers key:

{
  "context_servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

The legacy mcpServers key is still accepted on read. Set "disabled": true on a server entry to keep it in the unified store without exporting it - sync skips disabled servers even when they are named in an include list.

Commands

ai-config init [--fresh]

Initialize new configuration structure.

ai-config init           # Initialize new config
ai-config init --fresh   # Remove existing and start fresh

ai-config migrate [provider] [--project]

Migrate existing provider configurations.

ai-config migrate              # Migrate all detected providers
ai-config migrate devin        # Migrate specific provider
ai-config migrate --project    # Migrate project configs
ai-config migrate --dest PATH  # Migrate into an alternate unified root
ai-config migrate --no-interactive     # Quarantine skill conflicts without prompting
ai-config migrate --reconcile-aliases  # Move legacy <name>.<provider> dirs to skill-conflicts/

On a TTY, migrate first asks where migrated config should land: the default user store (~/.agents) or a custom path. --dest PATH answers that question up front and --no-interactive silently keeps the default, so scripts never block. Everything that normally lands under ~/.agents (skills, config/mcp-config.json, the lockfile, skill-conflicts/) lands under the chosen root instead. --dest does not apply to --project, whose destination is the project's own .agents/ dir.

On a TTY, migrate asks how to resolve each same-name skill conflict (keep / replace / skip); otherwise the incoming copy is quarantined under skill-conflicts/<name>/<provider>/ next to the skills dir.

ai-config validate

Validate configuration setup.

ai-config validate

ai-config status

Show current configuration status. When a skills lockfile exists, also reports per-provider skill state (in sync, stale, drifted, missing) and any recorded conflicts. Reading live hashes refreshes the lockfile in place: source entries are reconciled with the skills dir and conflict records whose parked copies were removed are pruned.

ai-config status

ai-config init-project

Initialize .agents/ directory in current project. Legacy .ai/ directories are still detected and used.

ai-config init-project

ai-config get-config <provider>

Get configuration for a specific provider.

ai-config get-config devin

ai-config sync [--provider NAME] [--project] [--all] [--prune] [--dry-run]

Write the unified config back to each provider's native files: MCP servers (translated to each provider's format: mcpServers, servers, context_servers, TOML mcp_servers, or YAML lists), rules (as a managed block in CLAUDE.md/AGENTS.md/etc., or dedicated rule files), provider settings, and skills.

ai-config sync --dry-run      # preview all writes
ai-config sync                # sync providers opted in via config
ai-config sync --provider cursor   # one provider, explicit
ai-config sync --all          # every known provider, explicit
ai-config sync --project      # project-level targets (.cursor/, .vscode/, ...)
ai-config sync --prune        # also remove MCP servers no longer in scope

Skills sync is symlink-only: each provider's skills dir links to the unified copy, so a skill edited in any provider edits the single source and nothing is ever duplicated. If a platform cannot create a symlink, sync reports an error rather than silently copying content. A provider rules file that holds only the unified AGENTS.md content is linked the same way.

Bare ai-config sync only writes to providers that opted in via "providers.<name>.sync": true. Providers can also read the unified config directly (see Provider Integration) without any file export.

Sync merges by default: existing keys in provider files are preserved, so servers added outside the unified config survive. Pass --prune to make a provider's MCP list an exact mirror of its scoped unified set and to remove synced skills that left scope; pruned MCP files are backed up with a .backup suffix first, and skills outside the .ai-config-skills manifest are left untouched. A skill name already claimed by a user-managed dir or file is preserved under .ai-config-backups/ in that skills dir - and so is a managed copy whose contents were edited locally since the recorded push (drift protection, via the skills lockfile).

Per-provider MCP scoping

MCP export is fail-closed: a provider receives only the servers named in its mcp.include list, set in ~/.agents/config/config.json. A provider with no mcp scope gets no servers at all, so the shared unified set can never flood a native file:

{
  "providers": {
    "cursor": { "mcp": { "include": ["github", "filesystem"] } },
    "claude": { "mcp": { "include": ["*"], "exclude": ["internal-tools"] } }
  }
}

include is the grant: a name list exports only those servers, ["*"] exports the whole active set. exclude then subtracts from the granted set

  • on its own it grants nothing. ai-config migrate seeds mcp.include with the names the provider already had, so a migrated provider keeps its own set and unified additions need an explicit opt-in. Sync warns when a targeted provider has no mcp scope. Servers marked "disabled": true in mcp-config.json are never exported, even when named in include.

Per-provider skills scoping

Skills follow the same scoping rules. Whole skill directories are synced (SKILL.md plus companion files like references/ and scripts/), and synced names are recorded in a .ai-config-skills manifest inside each provider's skills dir. --prune removes only skills recorded in that manifest, so skills you placed in a provider dir yourself are never deleted.

A skills lockfile (.ai-config-lock.json next to each skills root) tracks content hashes, createdAt/updatedAt, and provenance (imported:<provider> for migrated skills, github:<source> for skills installed by the npm skills CLI), plus a receipt of the hash last pushed to each provider. That lets ai-config status distinguish a stale copy from one drifted by local edits, and lets sync back drifted copies up instead of overwriting them.

{
  "skills": { "enabled": ["skill-a", "skill-b"] },
  "providers": {
    "cursor": { "skills": { "include": ["skill-a"] } },
    "devin": { "skills": { "enabled": false } }
  }
}

skills.enabled is a global allowlist (empty means all skills are candidates). providers.<name>.skills then narrows per provider: include allowlists, exclude removes, and "enabled": false opts the provider out of skill sync entirely - useful when a provider already reads another location (e.g. Devin scanning ~/.claude/skills), which would otherwise list every skill twice.

Same-name skills with different content never land in the store as <name>.<provider> aliases - a folder name that differs from the SKILL.md name: frontmatter cannot load as a skill. Migration quarantines conflicts under skill-conflicts/<name>/<provider>/ and records them in the lockfile; ai-config migrate --reconcile-aliases retires aliases left behind by older versions.

Rules synced into shared files (like a project AGENTS.md) are wrapped in <!-- BEGIN ai-config managed --> markers so repeated syncs update in place without touching the rest of the file.

ai-config set-config <provider> <key> <value>

Set configuration value for a provider.

ai-config set-config devin model your-model-name
ai-config set-config devin theme_mode dark

Provider Integration

Each AI provider should read from the unified configuration:

from universal_ai_config import UnifiedConfig, AgentEnv

# Initialize
env = AgentEnv()
config = UnifiedConfig(env)

# Get provider-specific config
devin_config = config.get_provider_config("devin")

# Get merged config (user + project)
merged_config = config.get_merged_config(cwd=Path.cwd())

Migration Details

The tool automatically detects and migrates from Devin, Windsurf, Claude, Cursor, Codex, Gemini, VS Code, Zed, and Continue - see the provider table above for the exact paths scanned. JSON, TOML, and YAML configs are all supported.

MCP servers are deduplicated on import: identical entries merge, and a same-name server with a different config is kept under a <name>.<provider> alias (e.g. github.cursor) rather than silently overwriting the existing one. Skills are deduplicated too: identical skills - and incoming copies whose files are all identical subsets of the existing skill - are skipped, while a conflicting same-name skill is quarantined under skill-conflicts/<name>/<provider>/ (prompting keep / replace / skip on a TTY). The whole skill directory, not just SKILL.md, is imported. Rules imports strip managed blocks and dedupe previously migrated chunks; once the unified AGENTS.md holds content it is the master copy, so divergent provider rules are reported for manual merge instead of appended.

Legacy configs are backed up with .backup extension.

Platform Support

All agent data lives under ~/.agents/ on every platform (Linux, macOS, Windows). Set the AGENT_CONFIG_HOME environment variable to relocate the base directory.

Project config dirs are .agents/ by default (legacy .ai/ also detected). Override the search list with AGENT_PROJECT_DIRS, a comma-separated list in precedence order - the first entry is the name ai-config init-project creates. Example:

export AGENT_PROJECT_DIRS=".mycfg,.agents,.ai"

Security: Project Configuration

When resolving project configuration, ai-config searches parent directories for .agents/ and .ai/ folders. Only project config directories owned by the current user are loaded - this prevents configuration injection from shared or world-writable workspaces, where another user could plant a malicious config.json or mcp-config.json (API keys, MCP servers) that would merge into your settings and be exported to provider files.

If a .agents/ or .ai/ directory is skipped, a SecurityWarning naming the path is emitted. On platforms where ownership cannot be verified (Windows), the config is loaded with a warning instead.

Best Practices

  1. Secrets Management: Never store API keys in config files. Use system keyrings or environment variables.

  2. Project Config: Use .agents/config.json for team settings and .agents/config.local.json for personal overrides.

  3. Shared Resources: Put common MCP servers and skills in user config; project-specific ones in .agents/.

  4. Validation: Always run ai-config validate after making changes.

Development

Setup Development Environment

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

Run Tests

pytest

Format Code

black universal_ai_config/

Type Check

mypy universal_ai_config/

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please read our contributing guidelines before submitting PRs.

Support

Metadata

Release files for universal-ai-config 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for universal-ai-config 0.3.0
File Size Uploaded Provenance Actions
universal_ai_config-0.3.0.tar.gz 63.2 kB With provenance Details for universal_ai_config-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for universal-ai-config 0.3.0
File Interpreter ABI Platform Actions
universal_ai_config-0.3.0-py3-none-any.whl Python 3 none any Details for universal_ai_config-0.3.0-py3-none-any.whl

Total release size: 112.1 kB

Release files / universal_ai_config-0.3.0.tar.gz

Download URL universal_ai_config-0.3.0.tar.gz
Size 63.2 kB
Tags Source
SHA-256 checksum
How to use checksums
fb62fb9c5343bc2fe4f6d36e9c038b4b82dca396161fc989dd0743479cb3b3aa
BLAKE2b-256 checksum
How to use checksums
b8b3bbdd6f83918d49a0de5505e065f544833a10e08f4088fb164c78cbd625b3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / universal_ai_config-0.3.0-py3-none-any.whl

Download URL universal_ai_config-0.3.0-py3-none-any.whl
Size 48.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1a697750622f4f92f2b4c6a0230fb0b1a61b0829f053eb3f967016736a887ac9
BLAKE2b-256 checksum
How to use checksums
172167aa8f73410b42909ac9b5780c86baf93fc3d066f47de405c0d0bbe1befc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Security for universal-ai-config 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for universal_ai_config-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page