ai.json Reference

ai.json is the single configuration file that aix uses to sync your AI editor settings. It supports JSONC (comments and trailing commas).

Lockfiles

ai.lock.json is an optional sibling file for ai.json. Create or refresh it with:

aix validate --lock

When ai.lock.json exists, aix reads it automatically. If the resolved config digest no longer matches, aix stops and asks you to refresh the lockfile. This catches edits to ai.json, inherited configs, local overrides, and resolved entities before aix writes editor files.

The lockfile stores SHA-512 integrity strings and SHA-256 digests for config entities such as skills, rules, prompts, MCP servers, hooks, and editor settings. Hashes prove the content matches the lockfile. They do not prove publisher identity.

Schema

Add the $schema field for IDE autocompletion and inline validation:

{
   "$schema": "https://x.a1st.dev/schemas/v1/ai.json"
}

Top-level fields

Field	Type	Description
$schema	string	JSON Schema URL for IDE validation
scope	string	"project" (default) or "user". Sets whether this is a project or user config
extends	string | string[]	Inherit from other configs
skills	object	Map of skill names to skill references
mcp	object	Map of server names to MCP server configs
rules	object	Map of rule names to rule definitions
prompts	object	Map of prompt names to prompt definitions
agents	object	Map of agent names to agent definitions
editors	object | string[]	Editor targeting and editor-specific settings
hooks	object	Lifecycle hooks for AI agent events
aix	object	aix tool settings (cache, backups)

---

scope

Sets whether this config manages project-level or user-level AI configuration. Defaults to "project" when omitted.

{
   "scope": "user"
}

When scope is "user", aix writes to user-level editor config locations (e.g., global MCP settings). When "project" (or omitted), aix writes to project-local config files.

---

extends

Inherit from other configurations. Supports a single string or an array. Configs are resolved and deep-merged in order — later entries override earlier ones.

{
   "extends": "github:company/ai-config"
}

{
   "extends": ["@company/aix-base", "github:team/project-overrides", "./local-overrides.json"]
}

Source types:

• npm package: "@company/aix-config" or "aix-config-react"
• Git shorthand: "github:user/repo", "gitlab:org/repo#v2.0"
• URL: "https://raw.githubusercontent.com/..."
• Local path: "./configs/base.json"

See Config Inheritance for merge semantics.

---

skills

Map of skill names to skill references. Skill names must be lowercase alphanumeric with hyphens (max 64 characters). See Skills for the full concept.

String shorthand

{
   "skills": {
      "react": "aix-skill-react",
      "custom": "./skills/custom",
      "remote": "github:user/skills#v2.0:skills/react"
   }
}

Object form

{
   "skills": {
      "react": {
         "source": {
            "git": "https://github.com/user/repo",
            "ref": "v2.0",
            "path": "skills/react"
         },
         "enabled": true,
         "config": {
            "framework": "nextjs"
         }
      }
   }
}

Disable an inherited skill

{
   "skills": {
      "inherited-skill": false
   }
}

---

mcp

Map of server names to MCP server configurations. See MCP Servers for the full concept.

Stdio transport

{
   "mcp": {
      "github": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-github"],
         "env": {
            "GITHUB_TOKEN": "${GITHUB_TOKEN}"
         },
         "cwd": ".",
         "shell": false
      }
   }
}

Field	Type	Default	Description
command	string	—	Command to run
args	string[]	[]	Command arguments
env	object	{}	Environment variables. Use ${VAR} for shell expansion.
cwd	string	.	Working directory
shell	boolean	false	Run in a shell

HTTP transport

{
   "mcp": {
      "remote-server": {
         "url": "https://example.com/mcp",
         "headers": {
            "Authorization": "Bearer ${TOKEN}"
         },
         "timeout": 30000
      }
   }
}

Field	Type	Default	Description
url	string	—	MCP endpoint URL (Streamable HTTP)
headers	object	{}	Request headers
timeout	number	—	Connection timeout in ms
validateOrigin	boolean	true	Validate server origin

Common options

These fields apply to both transport types:

Field	Type	Default	Description
enabled	boolean	true	Enable/disable the server
tools	string[] | object	—	Tool access control. Array of allowed tool names, or { include: [], exclude: [] }.
disabledTools	string[]	—	Tool names to disable
resources	string[] | object	—	Resource access control. Array of allowed patterns, or { include: [], exclude: [] }.
autoStart	boolean	true	Start with editor
restartOnFailure	boolean	true	Auto-restart on crash
maxRestarts	number	3	Max restart attempts

Disable an inherited server

{
   "mcp": {
      "inherited-server": false
   }
}

---

rules

Map of rule names to rule definitions. See Rules.

String shorthand

{
   "rules": {
      "code-style": "./rules/style.md",
      "remote-rule": "github:company/rules#main/typescript.md"
   }
}

Object form

{
   "rules": {
      "code-style": {
         "activation": "always",
         "content": "Always use TypeScript strict mode."
      },
      "testing": {
         "activation": "glob",
         "globs": ["**/*.test.ts", "**/*.spec.ts"],
         "path": "./rules/testing.md"
      },
      "security": {
         "activation": "auto",
         "description": "Apply when working on authentication or authorization code.",
         "path": "./rules/security.md"
      }
   }
}

Field	Type	Default	Description
activation	string	"always"	"always", "auto", "glob", or "manual"
description	string	—	When the rule applies (required for "auto" mode)
globs	string[]	—	File patterns (required for "glob" mode)
content	string	—	Inline rule text
path	string	—	Path to a markdown file
git	object	—	{ url, ref, path } for git-hosted rules
npm	object	—	{ npm, path, version } for npm-hosted rules

One source field (content, path, git, or npm) is required.

---

prompts

Map of prompt names to prompt definitions. See Prompts.

String shorthand

{
   "prompts": {
      "review": "./prompts/review.md",
      "plan": "./prompts/plan.md"
   }
}

Object form

{
   "prompts": {
      "review": {
         "description": "Review code changes for quality issues",
         "argumentHint": "[file] [message]",
         "path": "./prompts/review.md"
      }
   }
}

Field	Type	Description
description	string	Shown in the editor’s command picker
argumentHint	string	Hint for arguments (e.g., "[file] [message]")
content	string	Inline prompt text
path	string	Path to a markdown file
git	object	{ url, ref, path } for git-hosted prompts
npm	object	{ npm, path, version } for npm-hosted prompts

---

agents

Map of specialized agent names to agent definitions. See Agents.

String shorthand

{
   "agents": {
      "code-reviewer": "./agents/code-reviewer.md"
   }
}

Object form

{
   "agents": {
      "code-reviewer": {
         "description": "Review code changes",
         "mode": "subagent",
         "model": "sonnet",
         "tools": ["Read", "Grep"],
         "permissions": {
            "edit": "deny"
         },
         "content": "Review the current diff."
      }
   }
}

Field	Type	Description
description	string	When the editor should use the agent
mode	string	"primary" or "subagent"
model	string	Editor model alias or model ID
tools	array	Tool names available to the agent
permissions	object	Portable allow, ask, or deny capability policies
mcp	object	MCP servers available to this agent when supported
content	string	Inline agent instructions
path	string	Path to a markdown file
git	object	{ url, ref, path } for git-hosted agents
npm	object	{ npm, path, version } for npm-hosted agents
editor	object	Editor-specific fields keyed by editor ID for round-trip safety

---

editors

Configure which editors to install to and provide editor-specific settings.

Array shorthand

{
   "editors": ["cursor", "copilot", "claude-code", "opencode"]
}

Object form

{
   "editors": {
      "cursor": {
         "enabled": true,
         "rules": {
            "cursor-only": {
               "content": "Cursor-specific instructions here"
            }
         },
         "aiSettings": {}
      },
      "windsurf": {
         "enabled": true,
         "cascadeSettings": {}
      },
      "claude-code": {
         "enabled": true,
         "permissions": {}
      },
      "opencode": {
         "enabled": true
      }
   }
}

If editors is omitted, aix auto-detects installed editors at install time. See Editor Configuration.

---

hooks

Lifecycle hooks for AI agent events. See Hooks.

{
   "hooks": {
      "session_start": [
         {
            "matcher": ".*",
            "hooks": [
               {
                  "command": "echo 'Session started'",
                  "timeout": 5,
                  "show_output": true
               }
            ]
         }
      ]
   }
}

---

aix

Settings for the aix tool itself. These don’t affect AI editor behavior.

{
   "aix": {
      "cache": {
         "maxBackups": 5,
         "maxBackupAgeDays": 30,
         "maxCacheAgeDays": 7
      }
   }
}

Field	Type	Default	Range	Description
cache.maxBackups	number	5	1–100	Max backup files to keep
cache.maxBackupAgeDays	number	30	1–365	Max backup age before cleanup
cache.maxCacheAgeDays	number	7	1–365	Max cache age before cleanup