Configuration File

AI DevKit stores your project settings in a .ai-devkit.json file at your project root. This file is created by ai-devkit init and read by most other commands.

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.

{
  "version": "0.23.1",
  "environments": ["cursor", "claude", "codex"],
  "phases": [
    "requirements",
    "design",
    "planning",
    "implementation",
    "testing"
  ],
  "paths": {
    "docs": "docs/ai"
  },
  "memory": {
    "path": ".ai-devkit/memory.db"
  },
  "registries": {
    "codeaholicguy/ai-devkit": "https://github.com/codeaholicguy/ai-devkit.git"
  },
  "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"
}

• 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.

• Type: array of environment codes
• Required: yes

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

Value	Environment
cursor	Cursor
claude	Claude Code
github	GitHub Copilot
gemini	Gemini
grok	Grok
codex	Codex
kilocode	Kilocode
amp	Amp
opencode	opencode
roo	Roo
antigravity	Antigravity
antigravity-cli	Antigravity CLI
junie	Junie
cline	Cline
devin	Devin
pi	Pi

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

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

• Type: array of phase names
• Required: yes

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

Value	Description
requirements	Requirements & Problem Understanding
design	System Design & Architecture
planning	Project Planning & Task Breakdown
implementation	Implementation Guide
testing	Testing Strategy
deployment	Deployment Strategy
monitoring	Monitoring & Observability

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

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

• Type: object
• Optional

Sub-field	Type	Default	Description
docs	string	docs/ai	Directory for phase document templates. Relative paths resolve from the project root.

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

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

• Type: object
• Optional

Sub-field	Type	Default	Description
path	string	.ai-devkit/memory.db	Path to the SQLite memory database. Absolute paths are used as-is. Relative paths resolve from the directory containing .ai-devkit.json.

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

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

• 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

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

List of installed skills. Duplicates are automatically deduplicated.

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

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

• 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:

Field	Required	Type	Description
transport	Yes	"stdio"
command	Yes	string	Command to execute
args	No	string[]	Command arguments
env	No	Record<string, string>	Environment variables

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

http or sse transport — connects to a remote server:

Field	Required	Type	Description
transport	Yes	"http" or "sse"
url	Yes	string	Server URL
headers	No	Record<string, string>	HTTP headers (e.g., for authentication)

"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

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

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

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

• 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.

• Type: object
• Optional

Global memory settings used by plugin runtime APIs.

Sub-field	Type	Default	Description
path	string	memory.db	Path exposed by runtime.getMemoryDbPath() for plugins. Absolute paths are used as-is. Relative paths resolve from ~/.ai-devkit, the directory containing the global config file.

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.

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.

Command	Creates	Modifies	Reads
ai-devkit init	Yes	Yes	Yes
ai-devkit install	No	No	Yes
ai-devkit phase	No	Yes (adds phase)	Yes
ai-devkit skill add	No	Yes (adds skill)	Yes
ai-devkit skill remove	No	Yes (removes skill)	Yes
ai-devkit skill update	No	Yes	Yes
ai-devkit plugin add	Yes (global)	Yes (global)	Yes (global)
ai-devkit plugin remove	No	Yes (global)	Yes (global)
ai-devkit plugin list	No	No	Yes (global)
ai-devkit memory *	No	No	Yes (reads memory.path)
ai-devkit lint	No	No	Yes

• 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