Provider Integration

Provider Integration

How AI providers (Devin, Windsurf, Claude, etc.) integrate with the universal configuration system. Runtime dependencies are small (tomli on Python <3.11, tomli-w, pyyaml), so it is safe to add to any provider.

What the system provides

• Single source of truth: all providers read ~/.agents/config/config.json
• Project-local overrides: .ai/config.json and .ai/config.local.json
• Shared resources: MCP servers and skills shared across providers
• Provider overrides: per-provider settings inside the same file

1. Add the dependency

pip install universal-ai-config

or add universal-ai-config to your requirements.txt / pyproject.toml.

2. Read configuration

from universal_ai_config import UnifiedConfig, AgentEnv
from pathlib import Path

env = AgentEnv()
config = UnifiedConfig(env)

# Provider-specific settings
provider_config = config.get_provider_config("your-provider")

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

3. Apply the config

model = provider_config.get("model", "default-model")

permissions = provider_config.get("permissions", {})
allow_rules = permissions.get("allow", [])
deny_rules = permissions.get("deny", [])
ask_rules = permissions.get("ask", [])

for name, server in provider_config.get("context_servers", {}).items():
    initialize_mcp_server(name, server)

skills = provider_config.get("skills", {})
enabled = skills.get("enabled", [])
paths = skills.get("paths", [])

4. Handle project-local config

Merge in precedence order: project local > project shared > provider > shared.

def get_effective_config(provider_name: str, cwd: Path) -> dict:
    env = AgentEnv()
    config = UnifiedConfig(env)
    effective = config.get_provider_config(provider_name)

    project_dir = env.project_config(cwd)
    if project_dir:
        for name in ("config.json", "config.local.json"):
            path = project_dir / name
            if path.exists():
                effective = deep_merge(effective, load_json(path))

    return effective

5. Fail soft

If the unified config does not exist, fall back to defaults instead of crashing:

from universal_ai_config import ConfigError

try:
    cfg = config.get_provider_config("your-provider")
except ConfigError:
    cfg = get_default_config()

6. Support migration

Register your provider in the registry (providers.py) so ai-config migrate imports its config and ai-config sync can write back to it:

from universal_ai_config.providers import PROVIDERS, ProviderSpec, SyncTargets

PROVIDERS["your-provider"] = ProviderSpec(
    name="your-provider",
    display="Your Provider",
    detect_paths=["~/.your-provider"],          # any existing path = installed
    read_paths={                                 # scanned during migration
        "user_config": ["~/.your-provider/config.json"],
        "user_mcp": ["~/.your-provider/mcp_config.json"],
        "project_config": [".your-provider/config.json"],
        "project_mcp": [".your-provider/mcp_config.json"],
    },
    user=SyncTargets(                            # where sync writes back
        config_file="~/.your-provider/config.json",
        mcp_file="~/.your-provider/mcp_config.json",
        mcp_key="mcpServers",
        mcp_style="map",                         # map | vscode | zed | list
        rules_path="~/.your-provider/AGENTS.md",
        rules_mode="file",                       # file | mdc_dir | md_dir
        skills_dir="~/.your-provider/skills",
    ),
)

Best practices

1. Do not duplicate config: read the unified file instead of maintaining your own.
2. Respect overrides: check providers.<name> before falling back to shared.
3. Auto-detect .ai/: apply project config whenever the cwd is inside a project.
4. Document your keys: list which settings your provider honors and their defaults.
5. No secrets in config: use keyrings or environment variables.

Testing the integration

ai-config init
ai-config set-config my-provider model my-model
ai-config get-config my-provider

cd your-project
ai-config init-project
ai-config set-config my-provider model project-model

Complete example

from universal_ai_config import UnifiedConfig, AgentEnv, ConfigError
from pathlib import Path

class MyAIProvider:
    def __init__(self, cwd: Path = None):
        self.env = AgentEnv()
        self.config = UnifiedConfig(self.env)
        self.cwd = cwd or Path.cwd()
        self._config = self._load()

    def _load(self) -> dict:
        try:
            return self.config.get_merged_config(cwd=self.cwd)
        except ConfigError:
            return {"model": "default-model", "permissions": {},
                    "context_servers": {}, "skills": {}}

    @property
    def model(self) -> str:
        return self._config.get("model", "default-model")

    @property
    def mcp_servers(self) -> dict:
        return self._config.get("context_servers", {})

A longer worked example lives in PROVIDER_INTEGRATION.md in the repo.