/moai fix

The one-shot auto-fix command. It scans your code in parallel for errors, then fixes them in one pass.

Info

One-line summary: /moai fix is a “quick cleanup tool.” It sweeps up the accumulated lint errors and type errors in your code and fixes them at once.

Info

Slash command: In Claude Code, type /moai:fix to run this command directly. Typing just /moai shows the list of all available subcommands.

During development, imports get out of order, types stop matching, and lint warnings pile up. Instead of hunting these down one by one, run /moai fix and the AI finds and fixes the problems automatically.

Unlike /moai loop, it runs exactly once, making it the right fit when you want to clean up the current state quickly. In the loop family, /moai fix is the one-shot (single-pass) preset — running a loop over clear-cut errors that need no iteration wastes tokens, so picking the cheapest tool that matches the size of the job is the right tokenomics call.

> /moai fix

Run it without arguments and it scans the current project for errors and auto-fixes what it can.

Lets you preview what changes would be made, without applying them:

> /moai fix --dry

With this option, no actual code is modified — only the discovered issues and expected changes are displayed.

Limits the levels to be fixed:

# Fix Level 1-2 only (formatting, lint)
> /moai fix --level 2

# Fix Level 1 only (formatting only)
> /moai fix --level 1

/moai fix runs in 5 steps.

flowchart TD
    Start["/moai fix run"] --> Scan

    subgraph Scan["Step 1: parallel scan"]
        S1["LSP scan
type error check"]
        S2["AST-grep scan
structural pattern check"]
        S3["Linter scan
code style check"]
    end

    Scan --> Collect["Step 2: issue collection"]
    Collect --> Classify["Step 3: level classification
(Level 1~4)"]
    Classify --> Fix["Step 4: auto/approved fixes"]
    Fix --> Verify["Step 5: verification"]
    Verify --> Done["Done"]

Three tools scan the code simultaneously.

The scan results are merged into a single list.

Issues found (example):
  [Level 1] src/api/router.py:3 - imports need sorting
  [Level 1] src/models/user.py:15 - unnecessary whitespace
  [Level 2] src/utils/helper.py:8 - unused variable "temp"
  [Level 2] src/auth/service.py:22 - unnecessary else clause
  [Level 3] src/auth/service.py:45 - missing error handling
  [Level 4] src/db/connection.py:12 - possible SQL injection

The collected issues are classified into 4 levels by risk. Whether an issue is auto-fixed depends on its level. The safe things are handled by the machine, the risky ones get human approval — the harness design principle of pairing autonomy with safety gates applies here too.

flowchart TD
    Issue[Discovered issue] --> L1{Level 1?}
    L1 -->|Yes| Auto1["Auto-fix
no approval needed"]
    L1 -->|No| L2{Level 2?}
    L2 -->|Yes| Auto2["Auto-fix
log only"]
    L2 -->|No| L3{Level 3?}
    L3 -->|Yes| Approve3["Fix after
user approval"]
    L3 -->|No| Approve4["User approval required
manual review recommended"]

Cosmetic problems that do not affect the code’s behavior. The AI fixes them automatically.

Actual fix example:

# Before (Level 1 issue)
import os
import sys
from pathlib import Path
import json

# After (auto-fixed)
import json
import os
import sys
from pathlib import Path

Minor problems that affect code quality. The AI fixes them automatically and logs the change.

Actual fix example:

# Before (Level 2 issue)
def get_user(user_id):
    result = db.query(user_id)
    if result:
        return result
    else:           # unnecessary else
        return None

# After (auto-fixed)
def get_user(user_id):
    result = db.query(user_id)
    if result:
        return result
    return None

Problems that can change the code’s behavior. Fixed after user approval.

What the user sees:

[Level 3] src/auth/service.py:45
  Problem: error handling for authentication failure is missing
  Proposal: add a try-except block to return a proper error response on auth failure

  Approve? (y/n)

Serious problems that affect security. User approval is mandatory, and manual review is recommended.

Warning

When a Level 4 issue is found, the AI does not fix it automatically. A badly fixed security vulnerability can create a bigger problem, so always verify it yourself before fixing.

Info

Selection guide:

• “I just want to clean up lint errors before committing” → /moai fix
• “There are many failing tests and I want them all fixed” → /moai loop

Because /moai fix is a one-shot (single) pipeline, issues that a single scan-fix-verify cannot resolve may remain. The kinds of remaining issues:

• Level 4 manual items (security · architecture — auto-fixing forbidden)
• Unresolved errors (items the repair stage could not fix)
• Phase 5 regression-guard failures (regressions that could neither be reverted nor reported)

When such residue remains, the fix workflow persists it to .moai/state/loop-verdict-<id>.json with exit_kind: "one-shot-residue" and iterations_used: 1. This schema is identical to /moai loop’s residue-persistence schema.

The report only suggests entering /moai loop for re-fixable residue; the fix workflow does not auto-invoke /moai loop or any other subcommand. When you re-enter /moai loop yourself, the persisted residue is incorporated as items in the loop’s scan queue, and the goal-preset sweep drains them.

The agent delegation flow of the /moai fix command:

flowchart TD
    User["User request"] --> Orchestrator["MoAI orchestrator"]
    Orchestrator --> Parallel["Parallel scan"]

    Parallel --> LSP["LSP scan"]
    Parallel --> AST["AST-grep scan"]
    Parallel --> Linter["Linter scan"]

    LSP --> Collect["Issue collection"]
    AST --> Collect
    Linter --> Collect

    Collect --> Classify["Level classification"]
    Classify --> Fix["Run fixes"]

    Fix --> Level12["Level 1-2
auto-fix"]
    Fix --> Level34["Level 3-4
approval required"]

    Level12 --> Verify["Verification"]
    Level34 --> UserApprove["User approval"]
    UserApprove --> Verify

    Verify --> Complete["Done"]

Agent roles:

Level 1 formatter cleanup (gofmt/prettier/ruff format, etc.) is performed directly by the orchestrator without an agent spawn. Fix-result verification is also done by the orchestrator re-running the scanners (LSP/AST-grep/linter) rather than by a separate audit agent.

You implemented a new feature and want to clean up the code before committing.

# Check the current state
$ ruff check src/
# 12 lint warnings found

# Run fix
> /moai fix

Execution log:

[Parallel scan]
  LSP: 2 errors found
  AST-grep: 3 pattern violations found
  Linter: 12 warnings found

[Issue classification]
  Level 1 (formatting): 7 → auto-fix
  Level 2 (lint): 8 → auto-fix
  Level 3 (logic): 2 → approval required
  Level 4 (security): 0

[Level 1-2 auto-fixes complete]
  - 5 import sorts
  - 2 trailing-whitespace removals
  - 3 unused-variable removals
  - 2 unnecessary-else removals
  - 2 type-hint fixes
  - 1 naming-rule fix

[Level 3 approval requests]
  Issue 1: src/auth/service.py:45
    Problem: missing error handling on token expiry
    Proposal: add TokenExpiredError exception handling
    → Approved: fixed

  Issue 2: src/api/router.py:78
    Problem: missing input validation
    Proposal: add input validation with a Pydantic model
    → Approved: fixed

[Verification]
  LSP errors: 0
  Linter warnings: 0
  All fixes verified.

Done: 17 issues fixed

Yes, Level 3-4 issues each require approval. However, you can check first with --dry and approve only the important ones.

You can revert with Git. It is a good idea to commit before fixing, or back up with git stash.

When /moai fix exits leaving residual issues (Level 4 manual items, unresolved errors, Phase 5 regression-guard failures), the residue is persisted to .moai/state/loop-verdict-<id>.json with exit_kind: "one-shot-residue". The report only suggests entering /moai loop for re-fixable residue (it does not auto-invoke it), and when you re-enter /moai loop this residue enters the loop queue as scan items.

/moai fix handles error fixing only. /moai automatically runs the entire workflow from SPEC creation through implementation to documentation.

• /moai loop - iterative fix loop
• /moai - fully autonomous automation
• TRUST 5 Quality System