Update

Keep MoAI-ADK up to date and perform smooth upgrades with the smart update workflow.

Update Command

To update MoAI-ADK to the latest version:


moai update

This command runs a 3-phase smart update workflow.

3-Phase Smart Update Workflow

Stage 1: Check Package Version

First, compare the currently installed version with the latest version on GitHub Releases.


# Check current version
moai --version
 
# Check available updates
moai update --check-only

Items Checked:

Currently installed version
GitHub Releases latest version
Changelog (new features, bug fixes, compatibility)

Output Example:


Current version: 1.2.0
Latest version: 1.3.0

Release notes:
- Add new expert-performance agent
- Improve token optimization
- Fix SPEC validation issues

Update available! Run 'moai update' to upgrade.

Stage 2: Compare Config Versions

Check configuration file format and compatibility.

Files Checked:

.moai/config/sections/user.yaml
.moai/config/sections/language.yaml
.moai/config/sections/quality.yaml

Migration Example:


# Old config (v1.2.0)
development_mode: ddd
test_coverage_target: 85
 
# New config (v1.3.0)
development_mode: ddd
test_coverage_target: 85
ddd_settings:
  require_existing_tests: true
  characterization_tests: true

Configuration files in .moai/config/ are always backed up before migration.

Stage 3: Template Sync

Synchronize project templates and base files to the latest version.

Files Synced:

.moai/templates/ - Project templates
.claude/skills/ - Skill templates
.claude/agents/ - Agent templates

User-modified template files are preserved, with merge options offered for new versions.

Update Options

Operation Modes

Command	Binary Update	Template Sync
`moai update`	O	O
`moai update --binary`	O	X
`moai update --templates-only`	X	O

Binary-Only Update

Update the MoAI-ADK binary only without syncing templates:


$ moai update --binary

Use cases:

When you have manually modified templates
When you want to skip template synchronization
When only binary update is needed

Template-Only Sync

Sync templates only without updating the binary:


$ moai update --templates-only

Use cases:

Apply latest skill and agent templates
Keep binary version while updating templates
When template sync is needed across multiple projects

Check Only

Check available versions without actual update:


$ moai update --check-only

Auto Update

Automatically update without confirmation:


$ moai update --yes

Specific Version

Update to a specific version:


$ moai update --version 1.2.0

Keep Backup

Preserve backup for recovery if update fails:


$ moai update --keep-backup

Post-Update Procedures

Step 1: Check Version


moai --version

Step 2: Verify Configuration


moai doctor

Step 3: Check New Features


moai --help

Check for newly added commands or options.

Troubleshooting

Problem: Update Failed


Error: Update failed - permission denied

Solution:


# Manual reinstall with curl
curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bash
 
# Or reinstall a specific version
moai update --version <VERSION>

Problem: Config Migration Error


Error: Config migration failed

Solution:


# Restore from backup
cp -r .moai/config.bak .moai/config
 
# Manual migration
vim .moai/config/sections/quality.yaml

Problem: Template Conflicts


Warning: Template conflicts detected

Solution:


# Auto merge (preserve user changes)
$ moai update --merge
 
# Manual merge (preserve backup, create merge guide)
$ moai update --manual
 
# Force update (no backup)
$ moai update --force

Personal Settings Management

When updating MoAI-ADK, CLAUDE.md and settings.json are overwritten with new versions. If you have personal modifications, manage them as follows.

Using .local Files

Store personal settings in separate files to prevent overwriting during updates:

File	Location	Purpose
`CLAUDE.md`	Project root	MoAI-ADK managed (changed on update)
`settings.json`	`.claude/`	MoAI-ADK managed (changed on update)
`CLAUDE.local.md`	Project root	✅ Project personal settings (not affected by update)
`.claude/settings.local.json`	Project	✅ Project personal settings (not affected by update)

Personal Settings Example (Project Local):


# CLAUDE.local.md
 
## User Information
 
- Name: John Developer
- Role: Senior Software Engineer
- Expertise: Backend Development, DevOps
 
## Development Preferences
 
- Languages: Python, TypeScript
- Frameworks: FastAPI, React
- Testing: pytest, Jest
- Documentation: Markdown, OpenAPI

Personal Settings Example (settings):


// .claude/settings.local.json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR-API-KEY",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7-flashx",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.7"
  },
  "permissions": {
    "allow": [
      "Bash(bun run typecheck:*)",
      "Bash(bun install)",
      "Bash(bun run build)"
    ]
  },
  "enabledMcpjsonServers": [
    "context7"
  ],
  "companyAnnouncements": [
    "🗿 MoAI-ADK: 28 Specialized Agents + 52 Skills with SPEC-First DDD",
    "⚡ /moai: One-stop Plan→Run→Sync automation with intelligent routing",
    "🌳 moai worktree: Parallel SPEC development in isolated worktree environments",
    "🤖 Expert Agents (8): backend, frontend, security, devops, debug, performance, refactoring, testing",
    "🤖 Manager Agents (8): git, spec, ddd, tdd, docs, quality, project, strategy",
    "🤖 Builder Agents (3): agent, skill, plugin",
    "🤖 Team Agents (8, experimental): researcher, analyst, architect, designer, backend-dev, frontend-dev, tester, quality",
    "📋 Workflow: /moai plan (SPEC) → /moai run (DDD) → /moai sync (Docs)",
    "🚀 Options: --team (parallel Agent Teams), --ultrathink (deep analysis via Sequential Thinking MCP), --loop (iterative auto-fix)",
    "✅ Quality: TRUST 5 + ≥85% coverage + Ralph Engine (LSP + AST-grep)",
    "🔄 Git Strategy: 3-Mode (Manual/Personal/Team) with Smart Merge config updates",
    "📚 Tip: moai update --templates-only syncs latest skills and agents to your project",
    "📚 Tip: moai worktree new SPEC-XXX creates isolated worktree for parallel development",
    "⚙️ moai update -c: Configure Model availability (high/medium/low) based on your Claude plan tier",
    "💡 Hybrid Mode: Plan with Claude (Opus/Sonnet), Run/Sync with GLM-5 for cost savings",
    "💡 Parallel Dev: Terminal 1 runs Claude, Terminal 2+ run 'moai glm && claude' for parallel execution",
    "💎 GLM-5 Sponsor: z.ai partnership - cost-effective AI with equivalent performance"
  ],
  "_meta": {
    "description": "User-specific Claude Code settings (gitignored - never commit)",
    "created_at": "2026-01-27T18:15:26.175926Z",
    "note": "Edit this file to customize your local development environment"
  }
}

Configuration Priority: Local > Project > User > Enterprise
settings.local.json overrides project settings.

moai Folder Structure

MoAI-ADK only manages files in the following folders:


.claude/
├── agents/
│   └── moai/                # MoAI-ADK agents (update target)
│
├── hooks/
│   └── moai/                # MoAI-ADK hook scripts (update target)
│
├── skills/
│   ├── moai-*               # MoAI-ADK skills (moai- prefix, update target)
│   │
│   └── my-skills/           # ✅ Personal skills (not updated)
│
└── rules/
    └── moai/                # Rule files (moai managed)
        ├── core/            # Core principles and constitution
        ├── development/     # Development guidelines and standards
        ├── languages/       # Language-specific rules (16 languages)
        └── workflow/        # Workflow phase definitions

Naming Conventions:

Type	Location	Update Impact
Agents	`agents/moai/`	⚠️ Changed on update
Hooks	`hooks/moai/`	⚠️ Changed on update
Skills	`skills/moai-*`	⚠️ Changed on update
Rules	`rules/moai/`	⚠️ Changed on update
Personal Agents	`agents/my-agents/`	✅ Not affected by update
Personal Skills	`skills/my-skills/`	✅ Not affected by update

Important: Skills with moai-* prefix are managed by MoAI-ADK. Use my-* folders or separate prefixes for personal additions or modifications.

Important: Files in moai/ folders may be overwritten during updates. Use separate folders for personal additions or modifications.

How to Organize Files


# Move personal agents (example)
mv .claude/agents/my-agent.md .claude/my-agents/
 
# Move personal skills (example)
mv .claude/skills/my-skill.md .claude/my-skills/

Changelog

Check GitHub Releases for recent changes.

Rollback

If problems occur after update, you can rollback to a previous version:


# Rollback to specific version
moai update --version 1.2.0
 
# Or restore from backup
cp -r .moai/config.bak .moai/config

Commit your work before rollback.

Next Steps

After completing update:

Check Changelog - Learn new features
Core Concepts - Master new agents and features
Quick Start - Apply new features to your project

Update regularly to take advantage of the latest features and improvements in MoAI-ADK!