Trust But Verify: Previewing AI Agent Configs Before They Hit Your Repo

Here's a scenario that's happened to every developer who uses AI config tools: you run the generator, it overwrites your carefully customized CLAUDE.md, and now you're git checkout-ing to undo the damage.

The fix is simple: preview before you write.

The --dry-run Flag

aitoolkitplus init --all --12factor --dry-run

Output:

Analyzing /home/user/my-project ...

  Detected:
    Languages:   TypeScript, Go
    Frameworks:  Next.js, React, Tailwind CSS, Vitest

  Generating configs for: claude, cursor, copilot, windsurf, codex, gemini, mcp [12-factor] [dry-run]

  Would generate:
    [claude] CLAUDE.md
    [claude] .claude/settings.json
    [cursor] .cursorrules
    [cursor] .cursor/rules/framework.mdc
    [copilot] .github/copilot-instructions.md
    [windsurf] .windsurfrules
    [codex] AGENTS.md
    [codex] codex.md
    [gemini] GEMINI.md
    [mcp] .well-known/mcp.json
    [mcp] mcp-config.json

  Dry run complete. No files were written.

No files touched. You see exactly what would be created, which agents are involved, and which flags are active. Then you decide whether to proceed.

Why Dry-Run Matters More Than You Think

1. Existing Customizations

If you've hand-tuned your CLAUDE.md with project-specific instructions, a blind init will overwrite them. Dry-run lets you check if the regenerated version would replace something you care about.

2. CI Safety

In CI pipelines, you want to detect config drift without modifying the build:

- name: Check config freshness
  run: |
    aitoolkitplus init --all --dry-run --json | jq length
    # If output differs from committed files, flag it

3. Onboarding Confidence

New team members can preview what the tool will do before trusting it with their local setup. Lower barrier to adoption.

Combining with --json

For programmatic use, --dry-run pairs with --json:

aitoolkitplus init --all --dry-run --json

[
  {"agent": "claude", "path": "CLAUDE.md"},
  {"agent": "claude", "path": ".claude/settings.json"},
  {"agent": "cursor", "path": ".cursorrules"},
  {"agent": "mcp", "path": ".well-known/mcp.json"}
]

Pipe this into your deployment scripts, config validation, or dashboard tooling.

The Mental Model

Think of AI agent configs like database migrations. You wouldn't run migrate up without first checking what's about to change. --dry-run gives you that same safety for your AI tooling layer.

# Preview
aitoolkitplus init --all --dry-run

# Looks good? Run for real
aitoolkitplus init --all

# Want to lock in preferences?
aitoolkitplus init --all --save-config

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