Agent Setup

AI DevKit separates machine integration from project workflow configuration:

1. Run ai-devkit setup once per machine. It connects detected local agents, installs their available session integrations, and installs built-in skills globally.
2. Run ai-devkit init once per project. It creates .ai-devkit.json, workflow docs, and environment-specific project templates.
3. Run ai-devkit install later when you need to reconcile installable project artifacts from .ai-devkit.json.

Start with the complete Getting Started flow, including the separate global-install, npx-only, and CI paths.

For teams adopting AI coding agents across multiple tools, this setup becomes the shared foundation of the control plane: one config that generates workflow docs, skills, MCP server files, and environment-specific instructions.

Before running these commands:

• Install AI DevKit (npm install -g ai-devkit) and run ai-devkit setup, or use npx ai-devkit@latest setup
• Run commands from your project root directory
• Make sure you have permission to create or update agent-related files in the repository

Global npm installation does not run setup automatically. If you use npx only, prefix every command on this page with npx ai-devkit@latest.

Key concepts:

• Environment: An AI coding tool you use in the project. AI DevKit generates the configuration files each environment expects.
• Phase: A stage of the software development lifecycle, such as requirements, design, or testing. AI DevKit provides document templates for each phase.

Use ai-devkit setup when:

• You are connecting AI DevKit to agents on a machine for the first time
• You installed or launched another supported agent and want AI DevKit to detect it
• You need to restore global built-in skills or a session integration

Use ai-devkit init when:

• You are setting up AI DevKit in a project for the first time
• You want interactive prompts to choose environments and phases
• You want non-interactive bootstrap from a template file (ai-devkit init --template)
• You need project workflow docs and environment-specific templates

Use ai-devkit install when:

• .ai-devkit.json already exists
• You want deterministic setup without re-answering prompts
• You want to restore missing agent files or command folders to match your config

After completing machine setup, the simplest project path is interactive initialization. This walks you through choosing environments and phases:

ai-devkit init

Once .ai-devkit.json exists in your project, apply or re-apply the setup with:

ai-devkit install

After install completes successfully, you should usually see:

• .ai-devkit.json in your project root
• Environment-specific skill folders such as .cursor/skills/, .claude/skills/, .github/skills/, or .agents/skills/
• MCP config files such as .mcp.json or .codex/config.toml if your config includes MCP servers for supported environments

After running, you will see a summary like:

✔ Install Summary
  ✔ 3 environment(s) installed
  ✔ 5 phase template(s) installed
  ✔ 2 skill(s) installed

Use a non-default config file if your project stores AI DevKit config elsewhere:

ai-devkit install --config ./.ai-devkit.team.json

Overwrite existing install artifacts without extra prompts:

ai-devkit install --overwrite

Based on your configured environments, AI DevKit installs or updates files such as:

• Agent skill files (for example .cursor/skills/, .claude/skills/, .github/skills/ for GitHub Copilot, .devin/skills/, and .agents/skills/ for Codex) refer Skills for more on skills
• MCP server configuration files (.mcp.json for Claude Code and GitHub Copilot, .codex/config.toml for Codex, opencode.json for opencode, .junie/mcp/mcp.json for Junie, .devin/config.json for Devin, .roo/mcp.json for Roo Code, .kilo/kilo.jsonc for Kilo Code)
• Other environment-specific templates defined by AI DevKit

The exact artifacts depend on the environments configured in .ai-devkit.json. ai-devkit install only manages project-local files generated from that config.

Once .ai-devkit.json is committed to your repository, teammates and CI pipelines can reproduce the same setup with a single command:

ai-devkit install

Each teammate still needs the AI DevKit CLI available locally. With a global installation, run ai-devkit setup once and then use ai-devkit install. With npx only, use npx ai-devkit@latest setup once and prefix the install command too: npx ai-devkit@latest install.

For repeatable, non-interactive setup, create a template file. This is useful for sharing a standard configuration across teams or running in CI.

Create a file named fullstack-engineer.yaml in your project root with this content:

environments:
  - cursor
  - claude
  - codex
phases:
  - requirements
  - design
  - planning
  - implementation
  - testing
paths:
  docs: docs/ai
skills:
  - registry: codeaholicguy/ai-devkit
    skill: structured-debug
  - registry: codeaholicguy/ai-devkit
    skill: dev-lifecycle

Initialize from that template:

ai-devkit init --template ./fullstack-engineer.yaml

Use a custom directory for AI documentation in either interactive or template mode (default is docs/ai):

ai-devkit init --docs-dir ./ai-docs

Templates can include MCP server definitions. Add a mcpServers section to your template:

Note: mcpServers support requires AI DevKit 0.23.0 or later.

mcpServers:
  memory:
    transport: stdio
    command: npx
    args:
      - -y
      - "@ai-devkit/memory"

The -y flag lets npx run non-interactively, which is recommended for repeatable setup and CI.

After running ai-devkit init --template, MCP server definitions are saved to .ai-devkit.json. Run ai-devkit install to generate the agent-specific MCP config files. For the full mcpServers field reference, see Configuration File.

Field	Required	Description
environments	Yes*	List of AI environments to configure (cursor, claude, codex, etc.)
phases	Yes*	List of SDLC phases (requirements, design, planning, implementation, testing)
paths.docs	No	Custom directory for phase documents (default: docs/ai)
skills	No	List of skills to install, each with registry and skill fields
mcpServers	No	MCP server definitions (see MCP Servers for field details)

*If omitted, ai-devkit init will prompt you to select them interactively. Required for fully non-interactive runs.

For normal local onboarding, ai-devkit setup installs built-in skills globally for detected agents. In non-interactive environments such as CI, pass --built-in to init when the job needs project-local copies:

ai-devkit init --yes --environment <environment> --all --built-in

The --all flag selects all available phases. Combined with --yes, --environment, and --built-in, this gives a fully non-interactive project initialization.

When using a template with a skills section, skills from the template are installed from that configuration. Avoid combining the template with --built-in unless you intentionally want built-in skills added separately.

MCP (Model Context Protocol) servers give AI agents extended capabilities such as persistent memory, database access, or external tool integrations. Define MCP servers in .ai-devkit.json and AI DevKit generates the environment-specific config files for you.

Note: mcpServers generation and install flow require AI DevKit 0.23.0 or later.

MCP configuration is currently generated for Claude Code (.mcp.json), GitHub Copilot (.mcp.json), Codex (.codex/config.toml), opencode (opencode.json), Junie (.junie/mcp/mcp.json), Devin (.devin/config.json), Roo Code (.roo/mcp.json), and Kilo Code (.kilo/kilo.jsonc).

If your project uses only environments that do not currently support MCP generation, AI DevKit still saves the mcpServers definitions in .ai-devkit.json, but no environment-specific MCP config files are created.

You can define the same mcpServers configuration either in a template file used with ai-devkit init --template or directly in .ai-devkit.json. Both approaches work. After initialization, ai-devkit install always reads the final mcpServers values from .ai-devkit.json.

For the full mcpServers field reference, supported keys, and transport-specific examples, see Configuration File.

Add an mcpServers object to .ai-devkit.json like this:

{
  "mcpServers": {
    "memory": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@ai-devkit/memory"],
      "env": { "DB": "./db" }
    },
    "notion": {
      "transport": "http",
      "url": "https://mcp.notion.com/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

Then run ai-devkit install to generate the MCP config files for each supported environment.

When ai-devkit install finds an existing MCP server with the same name but different configuration:

• Interactive mode: You are prompted to skip, overwrite all, or choose per server.
• Non-interactive mode (CI): Conflicts are skipped by default. Pass --overwrite to force replacement.

Servers not managed by AI DevKit are preserved and never modified.

Run:

ai-devkit init

This creates the configuration file used by install.

If you prefer non-interactive setup, use the template command shown in Template-based Setup.

If you want to force replacement of install-managed artifacts, run:

ai-devkit install --overwrite

Re-run:

ai-devkit install

This re-applies setup using the current .ai-devkit.json content.

• Configuration File
• Supported AI Agents & Environments
• Getting Started
• Development with AI DevKit