Configuration File

AI DevKit stores project workflow, environment, skill, MCP, and memory settings in a .ai-devkit.json file at your project root. This file is created by ai-devkit init.

This is the project-scoped half of onboarding. Complete the machine setup first by following Getting Started.

There is also an optional global config at ~/.ai-devkit/.ai-devkit.json for settings that apply across all your projects.

Use this page as a reference for fields inside .ai-devkit.json. In most cases, prefer AI DevKit commands such as ai-devkit init, ai-devkit phase, and ai-devkit skill add to update the file for you. Edit the JSON directly only when you need to make a manual change that is not covered by a command.

Project Config (.ai-devkit.json)#

Full Example#

{
  "version": "0.70.1",
  "environments": ["cursor", "claude", "codex"],
  "phases": [
    "requirements",
    "design",
    "planning",
    "implementation",
    "testing"
  ],
  "paths": {
    "docs": "docs/ai"
  },
  "memory": {
    "path": ".ai-devkit/memory.db",
    "semantic": true
  },
  "registries": {
    "codeaholicguy/ai-devkit": "https://github.com/codeaholicguy/ai-devkit.git",
    "my-org/local-skills": "file:///absolute/path/to/local-registry"
  },
  "skills": [
    { "registry": "codeaholicguy/ai-devkit", "name": "structured-debug" },
    { "registry": "codeaholicguy/ai-devkit", "name": "dev-lifecycle" }
  ],
  "mcpServers": {
    "memory": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@ai-devkit/memory"]
    }
  },
  "createdAt": "2025-12-28T13:35:45.251Z"
}

Field Reference#

version#

• Type: string
• Set automatically when the config is created.
• Records which AI DevKit version created this file.
• You normally should not edit this field manually.

environments#

• Type: array of environment codes
• Required: yes

List of AI coding tools to generate configuration files for. Valid values:

"environments": ["cursor", "claude"]

Set by: ai-devkit init (interactive or --environment flag)

phases#

• Type: array of phase names
• Required: yes

Stages of the software development lifecycle that AI DevKit creates document templates for. Valid values:

"phases": ["requirements", "design", "planning", "implementation", "testing"]

Set by: ai-devkit init, ai-devkit phase

paths#

• Type: object
• Optional

"paths": {
  "docs": "docs/ai"
}

Set by: ai-devkit init --docs-dir <path> or template paths.docs field

memory#

• Type: object
• Optional

"memory": {
  "path": ".ai-devkit/memory.db",
  "semantic": true
}

Read by: ai-devkit memory store, ai-devkit memory search, ai-devkit memory update

registries#

• Type: Record<string, string>
• Optional

Maps custom registry IDs (e.g., owner/repo) to Git URLs. These are merged with the built-in registries when resolving skills. Project-level registries take priority over global registries, which take priority over built-in defaults.

"registries": {
  "codeaholicguy/ai-devkit": "https://github.com/codeaholicguy/ai-devkit.git",
  "my-org/custom-skills": "https://github.com/my-org/custom-skills.git"
}

Set by: ai-devkit init --template or by editing .ai-devkit.json directly

skills#

• Type: array of { registry, name, mode? }
• Optional

List of installed skills. Duplicates are automatically deduplicated.

mode controls how ai-devkit install puts each skill folder into your environments:

• link (default when mode is omitted): symlink to the cached skill. If symlinks cannot be created, AI DevKit copies the folder instead.
• copy: a real copy of the skill folder, for example when the files must work without the local skill cache.

"skills": [
  { "registry": "codeaholicguy/ai-devkit", "name": "structured-debug", "mode": "copy" },
  { "registry": "codeaholicguy/ai-devkit", "name": "dev-lifecycle" }
]

Existing installs are kept as they are. If a skill set to copy is still installed as a symlink, ai-devkit install reports a conflict and exits with a non-zero code; run ai-devkit install --overwrite to replace the symlink with a copy.

To set the mode when installing a skill, pass --mode copy or --mode link to ai-devkit skill add.

Modified by: ai-devkit skill add, ai-devkit skill remove, ai-devkit skill update, ai-devkit init --built-in

mcpServers#

• Type: Record<string, McpServerDefinition>
• Optional

Defines MCP servers that agents can connect to. Each key is the server name. This page covers the mcpServers field structure. For setup flow, generated files, and conflict behavior during install, see Agent Setup — MCP Servers.

Note: The mcpServers field is supported in AI DevKit 0.23.0 or later.

MCP settings can be stored either by initializing from a template or by editing .ai-devkit.json directly. ai-devkit install reads the final MCP settings from .ai-devkit.json and generates MCP config files only for environments that currently support MCP output.

Every server definition requires a transport field set to stdio, http, or sse. The remaining fields depend on the transport type:

stdio transport — runs a local process:

"memory": {
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@ai-devkit/memory"]
}

http or sse transport — connects to a remote server:

"notion": {
  "transport": "http",
  "url": "https://mcp.notion.com/mcp",
  "headers": {
    "Authorization": "Bearer your-token"
  }
}

Set by: ai-devkit init --template or by editing .ai-devkit.json directly Read by: ai-devkit install

createdAt#

• Type: string (ISO 8601 timestamp)
• Set automatically when the config is created.
• You normally should not edit this field manually.

Global Config (~/.ai-devkit/.ai-devkit.json)#

The global config file stores settings that apply across projects on your machine.

{
  "plugins": ["@ai-devkit/memory-dashboard"],
  "memory": {
    "path": "memory.db",
    "semantic": true
  },
  "agentRuntime": {
    "provider": "tmux"
  },
  "registries": {
    "codeaholicguy/ai-devkit": "https://github.com/codeaholicguy/ai-devkit.git",
    "my-org/custom-skills": "https://github.com/my-org/custom-skills.git"
  }
}

plugins#

• Type: array of npm package names
• Optional

Global AI DevKit plugins enabled for every invocation of the CLI. Use ai-devkit plugin add and ai-devkit plugin remove to update this field.

Plugin packages are installed under ~/.ai-devkit/npm/node_modules, not beside the AI DevKit binary. The first plugin system supports npm package names only; local paths, tarballs, git URLs, and version specs are not accepted by plugin add.

See Plugins for install commands, troubleshooting, and the plugin authoring contract.

memory#

• Type: object
• Optional

Global memory settings used by plugin runtime APIs.

If memory.path is not set in the global config, plugin runtime calls return ~/.ai-devkit/memory.db.

Project-level memory.path still controls ai-devkit memory * commands inside a project. Project-level memory.semantic overrides the global semantic setting.

agentRuntime#

• Type: object
• Optional

Selects the runtime used by interactive ai-devkit agent start and the console's start action.

Runtime selection is global-only. A project-level agentRuntime value is ignored.

registries#

Use the global config when you want the same custom skill registries available in every project on your machine without copying the same registry entries into each repository.

Global registries are merged with any project-level registries. If the same registry ID exists in both, the project-level entry takes priority.

The global config does not support project fields such as environments, phases, paths, skills, or mcpServers.

Which Commands Use the Config#

Related Pages#

• Agent Setup — how init and install use this config
• Skills — managing skills and registries
• Memory — configuring the memory database path
• Plugins — installing and authoring global npm plugins