AI coding tools each expect their own config directory — .claude/, .gemini/, .github/, .agents/. dotai creates a single .ai/ directory as your source of truth and symlinks everything to where each tool expects it.

Edit one file. Every tool stays in sync.

What's New in v3.1.0 — Resource Management Commands

Manage every aspect of your AI tool configuration from the CLI — MCP servers, skills, rules, slash commands, and config settings.

dotai mcp add my-server -c npx -a "my-pkg,serve,--stdio"   # add MCP server
dotai skill add code-review -d "Code review guidelines"    # add skill
dotai rule add api-conventions --always                     # add rule
dotai cmd add deploy                                        # add slash command
dotai config show                                           # view config

All commands auto-sync across every enabled tool — Claude, Gemini, Antigravity, and Copilot.

Also includes

• Spec-Driven Development (SDD) — 8-phase workflow for spec-traced code generation
• AI-Driven Knowledge Base — dotai knowledge init scaffolds the KB + /learn command; agents populate it
• Built-in /git-stage-commit — Stage, generate commit message, and commit locally (no push)
• 4 AI Tools — Gemini CLI, Antigravity, Claude Code, GitHub Copilot

Why dotai?

Without dotai, you juggle:

CLAUDE.md            ← Claude Code reads this
GEMINI.md            ← Gemini CLI reads this
.github/copilot-instructions.md  ← Copilot reads this
.gemini/rules/       ← Antigravity reads this

With dotai:

.ai/AI.md  →  symlinked to all of the above

One file to write. Four tools that read it. Zero drift.

Quick Start

# Install globally
npm install -g @nbslabs/dotai

# Initialize in your project
cd your-project
dotai init

# That's it — your .ai/ folder is ready and symlinks are created

How It Works

.ai/                           Your source of truth (committed to git)
├── AI.md               ──→    CLAUDE.md, GEMINI.md, AGENTS.md,
│                               .github/copilot-instructions.md
├── DOTAI.md                   Quick reference guide (this explains your setup)
├── rules/              ──→    .claude/rules/, .gemini/rules/,
│                               .agents/rules/
├── commands/           ──→    .claude/commands/
├── commands-gemini/    ──→    .gemini/commands/ (Gemini uses .toml format)
├── skills/             ──→    .claude/skills/, .gemini/skills/,
│                               .agents/skills/, .github/skills/
├── workflows/          ──→    .agents/workflows/
├── knowledge/          ──→    .claude/knowledge/, .gemini/knowledge/, .github/knowledge/
├── settings/
│   ├── claude.json     ──→    .claude/settings.json
│   └── gemini.json     ──→    .gemini/settings.json
└── ignore/
    └── .aiignore       ──→    .geminiignore

Commands

Core Commands

| Command | Description | |---|---| | dotai init | Scaffold .ai/ directory, or restore from existing .dotai.json | | dotai link [tools...] | Create symlinks for specified or all configured tools | | dotai unlink [tools...] | Remove symlinks, optionally restore backed-up originals | | dotai status | Show the current state of every symlink | | dotai add <tool> | Add a new tool to an existing project | | dotai remove <tool> | Remove a tool and clean up its symlinks | | dotai list | List all supported tools and their link status | | dotai sync | Re-evaluate and repair all symlinks | | dotai doctor | Run diagnostics and auto-fix issues | | dotai upgrade | Update .ai/ scaffold files to latest templates |

Resource Management (v3.1.0)

| Command | Description | |---|---| | dotai mcp add <name> | Add an MCP server to all enabled tool settings | | dotai mcp remove <name> | Remove an MCP server from all settings files | | dotai mcp list | List all configured MCP servers across tools | | dotai skill add <name> | Create a skill package with SKILL.md template | | dotai skill remove <name> | Delete a skill package | | dotai skill list | List all skills with descriptions and tool linkage | | dotai rule add <name> | Create a coding rule file with frontmatter | | dotai rule remove <name> | Delete a rule file | | dotai rule list | List all rules with alwaysApply status | | dotai cmd add <name> | Create a slash command across all enabled tool formats | | dotai cmd remove <name> | Remove a command from all formats | | dotai cmd list | List all commands merged across tool formats | | dotai config get <key> | Read a config value from .dotai.json | | dotai config set <key> <value> | Set a config value | | dotai config show | Display full configuration |

SDD (Spec-Driven Development)

| Command | Description | |---|---| | dotai sdd init | Scaffold SDD toolkit (skills, commands, templates) | | dotai sdd new <name> | Create a new feature directory from template | | dotai sdd remove <name> | Remove a feature and all its artifacts | | dotai sdd list | List all features and their current phase | | dotai sdd status [name] | Show detailed phase progress for a feature |

Supported Tools

| ID | Tool | Native Dir | What Gets Symlinked | |---|---|---|---| | claude | Claude Code | .claude/ | AI.md, settings, commands, skills, knowledge | | gemini | Gemini CLI | .gemini/ | AI.md, settings, commands (.toml), skills, ignore, knowledge | | copilot | GitHub Copilot | .github/ | AI.md, prompts, instructions, skills, knowledge | | antigravity | Antigravity | .gemini/ | AI.md, AGENTS.md, settings, rules, workflows, skills, knowledge |

Knowledge Base

dotai knowledge creates a persistent codebase memory layer at .ai/knowledge/ and equips your AI agents with the skills and commands to populate it.

Quick Start

dotai knowledge init   # scaffold knowledge dir + install /learn command

Then ask your AI agent:

/learn

The /learn command instructs the agent to deeply analyze your codebase and persist findings (architecture, patterns, gotchas) into .ai/knowledge/.

How It Works

1. dotai knowledge init creates:

   • knowledge/ directory with skeleton files (INDEX.md, patterns.md, gotchas.md, changelog.md)
   • skills/knowledge-scan-skill/SKILL.md — instructs agents how to perform deep analysis
   • /learn slash command for each enabled tool (Claude, Gemini, Antigravity, Copilot)

2. Your AI agent does the rest — using MCP tools (knowledge_explore, knowledge_append, knowledge_populate_ai_md) or by reading the skill directly. The agent understands semantics — it identifies patterns, gotchas, and architectural decisions that no static scanner can.

Why AI-driven? CLI scanners extract exports and file structure, but they miss context — why something is designed a certain way, what not to do, hidden dependencies. AI agents understand semantics and produce dramatically better knowledge.

Knowledge Commands

| Command | Description | |---|---| | dotai knowledge init | Scaffold knowledge directory + /learn command + scan skill | | dotai knowledge serve | MCP stdio server (runs independently, no init required) | | dotai knowledge status | Show knowledge base health | | dotai knowledge clean | Delete knowledge base for fresh start |

MCP Integration

The MCP server runs independently — no dotai init required. It auto-creates the knowledge directory if missing. Add to .ai/settings/claude.json:

{
  "mcpServers": {
    "dotai-knowledge": {
      "command": "npx",
      "args": ["dotai", "knowledge", "serve", "--stdio"]
    }
  }
}

IDE tools (Antigravity): Add "--project", "/path/to/your/project" to the args array. IDE-spawned processes may not use your project as the working directory.

Agents then have access to 7 MCP tools:

| Tool | Direction | Description | |------|-----------|-------------| | knowledge_query | 📖 Read | Search the knowledge base by keyword | | knowledge_get_module | 📖 Read | Get full summary of a specific module | | knowledge_list_modules | 📖 Read | List all indexed modules | | knowledge_recent_changes | 📖 Read | Get recent codebase changes | | knowledge_append | Write | Persist a finding (auto-creates missing files) | | knowledge_explore | 📖 Read | Read source files for deep AI analysis | | knowledge_populate_ai_md | ✏️ Write | Update AI.md project sections from codebase analysis |

Auto-Persist: How Agents Write Back

The AI.md template includes a mandatory auto-persist rule. When an agent reads or modifies code and discovers something non-obvious (a gotcha, a hidden dependency, a pattern), it is instructed to immediately call knowledge_append without waiting for user prompts.

Persistence happens during the session as a side-effect of work — not at session close. This means knowledge accumulates across conversations automatically:

Session 1:  Agent discovers 10 things → persists 8 → knowledge base grows
Session 2:  Agent reads knowledge → starts smart → discovers more → persists again
Session 3:  Even richer context from line one

Agents can also be prompted explicitly:

/learn The PaymentService.processRefund() requires ROLE_ADMIN — calling without it throws 403 silently

Troubleshooting: nvm + IDE-based tools

If Node.js is installed via nvm, IDE-spawned tools (Antigravity) can't find npx because they don't load .bashrc. Use the full path + explicit env in your settings JSON:

{
  "mcpServers": {
    "dotai-knowledge": {
      "command": "/home/YOUR_USER/.nvm/versions/node/vXX.XX.X/bin/npx",
      "args": ["dotai", "knowledge", "serve", "--stdio", "--project", "/path/to/your/project"],
      "env": {
        "PATH": "/home/YOUR_USER/.nvm/versions/node/vXX.XX.X/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Find your path: which npx

Developer Workflow

One-time setup:

dotai init                        # 1. create .ai/ + symlinks
dotai knowledge init              # 2. scaffold knowledge + /learn command
# 3. Ask your agent: /learn

Daily workflow:

Code normally → Open AI agent → reads knowledge → starts smart
→ discovers more → auto-persists via knowledge_append

SDD Toolkit

dotai sdd brings Spec-Driven Development (SDD) to your project — a structured workflow where every piece of AI-generated code traces back to a human-reviewed specification.

The 8-Phase Workflow

Phase 1: Initiate     → Human writes idea.md
Phase 2: Specify      → Agent generates requirements.md       ← Human review
Phase 3: Decompose    → Agent breaks into tasks/*.task.md     ← Human review
Phase 4: Plan         → Agent generates plans + evaluation    ← Human review
Phase 5: Implement    → Agent implements following the plan
Phase 6: Evaluate     → Agent verifies against acceptance criteria
Phase 7: Review       → Agent produces holistic code review   ← Human review
Phase 8: Context-sync → Agent updates .ai/knowledge/

Quick Start

# 1. Initialize SDD toolkit
dotai sdd init

# 2. Create a new feature
dotai sdd new user-authentication

# 3. Write your idea
# Edit .ai/sdd/user-authentication/idea.md

# 4. Run phases using your AI tool's native commands:
#    Claude: /sdd-specify user-authentication
#    Gemini: /sdd-specify user-authentication
#    Copilot: Use prompt sdd-specify
#    Antigravity: Use workflow sdd-specify

SDD Commands

| Command | Description | |---|---| | dotai sdd init | Scaffold skills, templates, and 28 cross-tool commands | | dotai sdd init --force | Re-write skills and commands (preserves feature dirs) | | dotai sdd new <name> | Create a new feature directory from template | | dotai sdd list | List all features with their current phase | | dotai sdd status [name] | Show phase-by-phase progress for a feature |

Cross-Tool Phase Commands

SDD generates native commands for all 4 supported tools:

| Phase | Claude / Gemini | Copilot | Antigravity | |---|---|---|---| | Specify | /sdd-specify | Prompt sdd-specify | Workflow sdd-specify | | Decompose | /sdd-decompose | Prompt sdd-decompose | Workflow sdd-decompose | | Plan | /sdd-plan | Prompt sdd-plan | Workflow sdd-plan | | Implement | /sdd-implement | Prompt sdd-implement | Workflow sdd-implement | | Evaluate | /sdd-evaluate | Prompt sdd-evaluate | Workflow sdd-evaluate | | Review | /sdd-review | Prompt sdd-review | Workflow sdd-review | | Sync | /sdd-sync | Prompt sdd-sync | Workflow sdd-sync |

Running Phase Commands

The argument to every phase command is the feature name — not an individual file:

# Claude / Gemini CLI:
/sdd-implement user-authentication

# If you omit the name, the agent lists features and asks:
/sdd-implement

How each phase processes work:

| Phase | Scope | Behavior | |-------|-------|----------| | Specify | Entire feature | Reads idea.md, produces one requirements.md | | Decompose | Entire feature | Reads requirements.md, produces all task files at once | | Plan | Entire feature | Generates plans and evaluation criteria for all tasks in one shot | | Implement | One task | Implements the lowest-indexed incomplete task, then stops and waits | | Evaluate | One task | Evaluates the most recently implemented task — PASS → next, FAIL → retry | | Review | Entire feature | Holistic review of the complete implementation | | Sync | Entire feature | Updates knowledge base with all decisions and patterns |

Implement and Evaluate are sequential by design. The agent works on one task at a time so you can inspect progress between tasks. Run /sdd-implement again to advance to the next task. If evaluation fails, the agent retries the same task automatically before moving on.

.ai/sdd/my-feature/
├── idea.md                        ← Phase 1: you write this
├── requirements.md                ← Phase 2: agent generates
├── tasks/
│   ├── 01_user_auth.task.md       ← Phase 3: agent generates
│   └── 02_api_routes.task.md
├── plans/
│   ├── 01_user_auth.plan.md       ← Phase 4: agent generates
│   └── 02_api_routes.plan.md
├── evaluation/
│   ├── 01_user_auth.evaluation.md ← Phase 4: acceptance criteria
│   ├── 01_user_auth.result.md     ← Phase 6: pass/fail verdict
│   └── ...
└── code-review.md                 ← Phase 7: holistic review

Resource Management

dotai v3.1.0 introduces CLI commands to manage all .ai/ resources without manually editing files.

MCP Servers

Add, remove, and list MCP server configurations across all enabled tool settings files.

# Add an MCP server to all tools
dotai mcp add my-server -c npx -a "@my-org/server,serve,--stdio"

# Add with environment variables
dotai mcp add db-server -c npx -a "db-mcp,--stdio" -e "DB_URL=postgres://localhost:5432/mydb"

# Add to only Claude
dotai mcp add claude-only-server -c npx -a "my-pkg" --tool claude

# List all configured servers
dotai mcp list

# Remove a server
dotai mcp remove my-server

Skills

Create and manage reusable skill packages in .ai/skills/.

dotai skill add code-review -d "Code review checklist"
dotai skill list
dotai skill remove code-review

Rules

Manage coding rule files in .ai/rules/ with YAML frontmatter.

dotai rule add api-conventions --always    # always apply
dotai rule add testing-guidelines          # on-demand
dotai rule list

Slash Commands

Create cross-tool slash commands. dotai cmd add creates format-appropriate files for every enabled tool:

| Tool | Directory | Format | |---|---|---| | Claude Code | commands/ | .md | | Gemini CLI | commands-gemini/ | .toml | | Antigravity | workflows/ | .md | | Copilot | prompts/ | .prompt.md |

dotai cmd add deploy         # creates files for all enabled tools
dotai cmd list               # shows commands merged across formats
dotai cmd remove deploy      # removes from all formats

Built-in Slash Commands

dotai init automatically creates these slash commands for all enabled tools:

| Command | Description | |---|---| | /review | Review code changes and provide feedback | | /deploy | Guide through the deployment process | | /learn | Deep codebase scan — populate .ai/knowledge/ | | /git-stage-commit | Stage all changes, generate commit message, commit locally (no push) |

/git-stage-commit also checks whether the knowledge base has been populated — if .ai/knowledge/ exists but is empty, it runs the /learn flow first.

Config

View and modify .dotai.json settings directly.

dotai config show            # dump full config
dotai config get tools       # get a specific key
dotai config set aiDir .ai   # set a value (restricted keys)

Usage

Initialize a new project (interactive)

dotai init

Note: If you have existing CLAUDE.md, GEMINI.md, or .github/copilot-instructions.md files, dotai init automatically detects them and imports their content into .ai/AI.md — nothing is lost.

Initialize with defaults (selects all tools)

dotai init --yes

Restore from .dotai.json after cloning

# If .dotai.json exists, dotai init reads it and sets up everything automatically
dotai init

Initialize with specific tools

dotai init --tools claude,gemini,copilot

Check symlink health

dotai status

Fix broken symlinks

dotai doctor --fix

Add a new tool later

dotai add copilot

Force re-link (backs up and replaces existing files)

dotai link --force --backup

Remove a tool

dotai remove gemini

Upgrade scaffold files to latest version

dotai upgrade              # smart update — new files, stale cleanup, manual review
dotai upgrade --dry-run    # preview without changes
dotai upgrade --force      # overwrite ALL files (destructive)

upgrade creates new template files, auto-updates reference docs, removes obsolete files from previous versions, and saves user-modified files to _upgrade/ for manual review.

The .ai/AI.md File

This is the heart of dotai. Write your project context once:

# AI Instructions — MyProject

## Architecture
- src/api/       — REST API routes (Express.js)
- src/services/  — Business logic layer
- src/models/    — Database models (Prisma)

## Tech Stack
- TypeScript 5.x, Node.js 20, PostgreSQL 16

## Key Commands
| Action | Command |
|--------|---------|
| Dev    | `npm run dev` |
| Test   | `npm test`    |
| Build  | `npm run build` |

## Important Constraints
- NEVER use `any` type
- ALWAYS run tests before committing

Every AI tool sees this content through its own native config path.

Platform Support

| Platform | Symlink Type | Notes | |---|---|---| | macOS / Linux | Standard symlinks | Works out of the box | | Windows 10+ | NTFS junctions (dirs) + symlinks (files) | No admin privileges needed |

All symlinks use relative paths for portability — move or clone the repo anywhere and dotai link recreates everything.

After Cloning

When a teammate clones the repo, they just run:

npm install -g @nbslabs/dotai  # if not already installed
dotai init            # reads .dotai.json, scaffolds missing files, links everything

dotai init detects the existing .dotai.json and automatically sets up the project — no prompts, no tool selection. Just like npm install reads package.json.

Git Integration

• ✅ Commit the .ai/ directory — it is your source of truth
• ✅ Commit .dotai.json — it tracks which tools are configured
• ❌ Don't commit .claude/, .gemini/, etc. — dotai adds them to .gitignore automatically

Development

git clone https://github.com/nbslabs/dotai-cli.git
cd dotai-cli
npm install
npm run dev     # Watch mode (rebuilds on save)
npm test        # Run test suite (Vitest)
npm run build   # Production build
npm run lint    # TypeScript type check

Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-thing)
3. Commit your changes (git commit -m 'Add amazing thing')
4. Push to the branch (git push origin feature/amazing-thing)
5. Open a Pull Request

License

MIT