ai-tree

Unified CLI to manage AI editor rules and MCP configs from a single source of truth. It generates and keeps in sync config files for Cursor, Windsurf, Copilot, Kiro, Codeium, Codex, VSCode, Zed, and OpenCode.

Why

• Single file to edit: Update ai-rules.json and sync everywhere.
• Repeatable: Idempotent apply regenerates the same outputs.
• Portable: Zero runtime deps; tiny TypeScript CLI.

Install

Until this is published to npm, clone the repo locally:

npm i
npm run build

When published, you’ll be able to run:

npx ai-tree --help

Quickstart

# 1) Initialize central config and scaffold all tool files
npx ai-tree init

# 2) Edit the single source of truth
$EDITOR ai-rules.json

# 3) Re-apply changes everywhere
npx ai-tree apply

Commands

• init: Create ai-rules.json (if missing) and generate all outputs.
• apply: Regenerate tool configs from ai-rules.json.
• list: Show files managed by this tool.
• clean: Remove generated files.
• doctor: Check expected directories and basic health.

Run npx ai-tree help to see usage.

Handling existing files safely

You might already have AI-related files (e.g. .cursor/mcp.json, .kiro/**, .vscode/mcp.json) before running this tool. To avoid surprises:

• Create a short-lived branch and run ai-tree init there first.
• The generator is idempotent and only writes when content changes; however, if the generated content differs, it will overwrite that file.
• README is protected via files.README with modes append | overwrite | skip to prevent clobbering your project docs.
• .gitignore is updated with an ai-tree managed block during init to ignore generated artifacts.
• Recommended workflow:
  1. Commit your current repository state.
  2. Run ai-tree init in a branch.
  3. Review the diff and copy any important pieces from existing configs into ai-rules.json as needed.
  4. Run ai-tree apply and merge once you're satisfied.

Notes:

• Global overwrite/backup/skip policies and a --dry-run preview are planned. For now, rely on branching and reviewing diffs for safety.

Configuration

All behavior is driven by ai-rules.json:

{
  "version": 1,
  "project": { "name": "my-repo", "description": "AI assistants unified rules" },
  "rules": {
    "global": ["Be precise"],
    "coding": ["Use meaningful names"]
  },
  "files": {
    "README": "append", // Readme mode: avoids accidental overwrites; choose "append"|"overwrite"|"skip" (true behaves like overwrite)
    "AGENT": true,
    "CONVENTIONS": true
  },
  "mcpServers": {
    "enableExamples": true,
    "servers": [
      { "id": "repo-fs", "command": "node", "args": ["-e", "console.log('placeholder')"] }
    ]
  }
}

What gets generated

Examples (depending on your config):

• .github/copilot-instructions.md
• .cursor/rules/instructions.mdc, .cursor/mcp.json
• .windsurf/rules/instructions.md, .codeium/windsurf/mcp_config.json
• .kiro/steering/instructions.md, .kiro/settings/mcp.json
• .codex/config.toml, .vscode/mcp.json, .zed/settings.json
• .windsurfrules, opencode.json, AGENT.md, CONVENTIONS.md

All of these are safe to delete and re-generate with ai-tree apply.

Contributing

Thanks for helping improve ai-tree! A few quick guidelines:

1. Prereqs: Node >= 16.14
2. Setup:
   • npm i
   • npm run build
   • Run locally via node dist/cli.js <command>
3. Branching: use short, descriptive branches like feat/windsurf-sync or fix/mcp-json.
4. Commits: follow Conventional Commits (feat:, fix:, docs:, refactor:...).
5. Style: TypeScript, strict mode. Prefer clear names and early returns.
6. Testing: if you add or change generators, include a small repo fixture or sample to exercise it manually.
7. PRs: keep them focused and include a short description of the change and any migration notes.

License

MIT