Quick Start

Quick Start

New users

ai-config init

This creates the unified directory structure under ~/.agents/:

~/.agents/
  config/          # config.json, mcp-config.json, AGENTS.md
  data/            # memory, plugins
  state/           # logs, history
  cache/           # model caches, venvs

Existing users (migration)

ai-config migrate

Detects existing configs from all supported providers (Devin, Windsurf, Claude, Cursor, Codex, Gemini, VS Code, Copilot CLI, Zed, Continue) and migrates them, backing up originals with a .backup extension. See Migration for details.

Per-project setup

Inside a git repository:

cd your-project
ai-config init-project

Creates .ai/ with shared team settings and updates .gitignore to exclude local overrides:

.ai/
  config.json            # shared team settings (committed)
  config.local.json      # personal overrides (gitignored)
  mcp-config.local.json  # personal MCP overrides (gitignored)
  skills/                # project skills
  AGENTS.md              # project rules

Everyday commands

ai-config status                            # what is configured
ai-config validate                          # check for problems
ai-config get-config devin                  # show a provider's config
ai-config set-config devin model my-model   # set a provider value

Values passed to set-config are parsed as JSON first, so booleans, numbers, arrays, and objects work:

ai-config set-config devin dark_mode true
ai-config set-config devin extra_tools '["git","npm"]'

Resulting directory layout

~/.agents/config/
  config.json        # unified config all providers read
  mcp-config.json    # shared MCP servers
  AGENTS.md          # shared rules
  skills/            # shared skills (each in a dir with SKILL.md)

~/.agents/data/      # long-term memory, datasets, plugins
~/.agents/state/     # logs, history, active sessions
~/.agents/cache/     # model caches, isolated environments

your-project/.ai/    # project-local config

Minimal config example

~/.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/", ".ai/skills/"]
  }
}

MCP servers live in ~/.agents/config/mcp-config.json under the context_servers key - see Configuration for the full format and precedence rules.