AI Toolkit Plus
Back to blog
March 24, 20263 min readAI Toolkit Plus Team

Why Every AI-Powered Repo Needs a Project Config File

AI agent configs drift as your codebase evolves. A persistent project config file solves the 'works on my machine' problem for AI tools. Here's how .aitoolkitplus.json works.

configdeveloper-experienceai-agentsbest-practices

You ran aitoolkitplus init --all --12factor --orchestrate three weeks ago. The configs were perfect. Then your team added a new service, switched from Jest to Vitest, and onboarded two new developers who have no idea what flags to pass.

Sound familiar? This is the AI config drift problem, and it's the #1 reason AI agent setups degrade over time.

The Problem: One-Shot Generation Doesn't Scale

Most AI config tools — including ours, until this release — treat config generation as a one-time event. You run a command, get your files, and move on. But codebases aren't static:

  • Dependencies change. You add a new framework, remove an old one, switch test runners.
  • Team preferences evolve. You adopt 12-factor patterns, start using worktrees, add new agents.
  • New developers join. They don't know the original flags. They run init with defaults and overwrite the team's carefully tuned setup.

The result? Your CLAUDE.md says you use Jest when you switched to Vitest two sprints ago. Your .cursorrules don't mention the FastAPI service you added last month. Your configs are lying to your AI agents.

The Solution: .aitoolkitplus.json

Starting with v0.2, AI Toolkit Plus supports a persistent project config file. It's simple:

json
{
  "agents": ["claude", "cursor", "copilot", "gemini", "mcp"],
  "twelve_factor": true,
  "worktree": true,
  "orchestrate": true,
  "exclude": ["legacy/", "vendor/"]
}

How It Works

Save once, use forever:

bash
# First time: configure everything and save
aitoolkitplus init --all --12factor --orchestrate --save-config

This generates your configs AND writes .aitoolkitplus.json with your preferences.

Update anytime:

bash
# Re-analyze codebase, regenerate configs with saved preferences
aitoolkitplus update

The update command reads your saved config, re-analyzes your codebase (detecting new frameworks, changed dependencies, etc.), and regenerates all configs with the same flags. No need to remember what you passed last time.

Team-friendly:

Commit .aitoolkitplus.json to your repo. Now every developer gets the same config generation behavior:

bash
# New developer joins, runs update
git clone your-repo && cd your-repo
aitoolkitplus update

They get the exact same AI agent configs the rest of the team uses, tailored to the current state of the codebase.

Config Merging

CLI flags always take precedence over the config file. This lets you experiment without changing the team default:

bash
# Team default is 12-factor off, but you want to try it
aitoolkitplus init --12factor

If you like the result, update the config:

bash
aitoolkitplus init --12factor --save-config

Why This Matters for Teams

The average AI-powered team uses 2.3 different AI coding agents (our data from beta users). Each agent has its own config format, its own conventions, its own quirks. Without a unified config source:

  • Agent A thinks you use npm. Agent B thinks you use yarn. Both are wrong — you switched to pnpm.
  • Developer Alice has orchestration configs. Developer Bob doesn't. Their AI agents behave differently on the same codebase.
  • CI generates configs with --all but nobody remembers to add --12factor.

.aitoolkitplus.json is the single source of truth for "how should AI agents understand this project."

Getting Started

bash
# Install or update
curl -fsSL https://aitoolkitplus.com/install.sh | bash

# Generate configs and save preferences
aitoolkitplus init --all --save-config

# From now on, just run update
aitoolkitplus update

The config file is designed to be committed alongside your code. It's small, human-readable, and version-controlled. When your codebase evolves, your AI agent configs evolve with it.

AI Toolkit Plus generates configuration files for Claude Code, Cursor, Copilot, Windsurf, Codex, and Gemini CLI from a single command. Learn more.