dotai

One .ai/ folder. All your AI tools. Always in sync. Always in context.

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.

hljs language-bash

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:

hljs language-kotlin

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:

hljs language-css

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

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

Quick Start

hljs language-bash

# 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

hljs language-bash

.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

hljs language-bash

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

Then ask your AI agent:

hljs language-bash

/learn

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

How It Works

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)
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:

hljs language-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:

hljs language-sql

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:

hljs language-java

/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:

hljs language-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:

hljs language-bash

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

Daily workflow:

hljs language-sql

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

hljs language-yaml

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

hljs language-bash

# 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:

hljs language-bash

# 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.

hljs language-yaml

.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.

hljs language-bash

# 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/.

hljs language-bash

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.

hljs language-bash

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`

hljs language-bash

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.

hljs language-bash

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)

hljs language-bash

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)

hljs language-bash

dotai init --yes

Restore from `.dotai.json` after cloning

hljs language-bash

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

Initialize with specific tools

hljs language-bash

dotai init --tools claude,gemini,copilot

Check symlink health

hljs language-bash

dotai status

Fix broken symlinks

hljs language-bash

dotai doctor --fix

Add a new tool later

hljs language-bash

dotai add copilot

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

hljs language-bash

dotai link --force --backup

Remove a tool

hljs language-bash

dotai remove gemini

Upgrade scaffold files to latest version

hljs language-bash

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:

hljs language-markdown

# 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:

hljs language-bash

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

hljs language-bash

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.

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

License

MIT

dotai-cli

dotai

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

Also includes

Why dotai?

Quick Start

How It Works

Commands

Core Commands

Resource Management (v3.1.0)

SDD (Spec-Driven Development)

Supported Tools

Knowledge Base

Quick Start

How It Works

Knowledge Commands

MCP Integration

Auto-Persist: How Agents Write Back

Troubleshooting: nvm + IDE-based tools

Developer Workflow

SDD Toolkit

The 8-Phase Workflow

Quick Start

SDD Commands

Cross-Tool Phase Commands

Running Phase Commands

Resource Management

MCP Servers

Skills

Rules

Slash Commands

Built-in Slash Commands

Config

Usage

Initialize a new project (interactive)

Initialize with defaults (selects all tools)

Restore from .dotai.json after cloning

Initialize with specific tools

Check symlink health

Fix broken symlinks

Add a new tool later

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

Remove a tool

Upgrade scaffold files to latest version

The .ai/AI.md File

Platform Support

After Cloning

Git Integration

Development

Contributing

License

Similar Packages

Tags

Original Author

Publisher

Restore from `.dotai.json` after cloning

The `.ai/AI.md` File