Deterministic auto-fix for mechanical slop

Mechanically fix reversible and low-risk findings, then use aislop agent or a prompt handoff for issues that need judgment.

aislop fix is the deterministic cleanup layer. It applies mechanical fixes first - unused imports, narrative comments, formatting, dead code - and can still print or open a structured prompt for older agent handoff flows. For the full local repair workflow with worktrees, provider setup, verification, sessions, and optional PR publishing, use aislop agent.

Fix workflow

Work through the stages in order to reach 100/100 with the least disruption to your codebase:

1. Run a plain scan to see everything

   Before touching anything, get the full picture.

   aislop scan
   
2. Apply only reversible fixes with --safe

   Start conservatively. --safe restricts the run to fixes that cannot change behaviour: unused-import removal, import merging, narrative-comment removal, and formatting. Apply these, review the diff, and commit.

   aislop fix --safe
   
3. Run the standard auto-fixer

   Without --safe, aislop also clears console-log leftovers, removes dead code, and runs lint autofixes. Review the diff before committing.

   aislop fix
   
4. Run aggressive fixes with --force

   --force adds dependency auditing, framework alignment checks, and unused-file removal. These are more disruptive, so review the diff carefully.

   aislop fix -f
   
5. Hand off remaining issues to your agent

   For the full local repair loop, run aislop agent. For prompt-based handoff, pass the remaining diagnostics to your coding agent with full diagnostic information:

   aislop agent # recommended local repair workflow
   aislop fix --claude # Claude Code
   aislop fix --codex # Codex CLI
   aislop fix --cursor # Cursor (copies prompt to clipboard)
   aislop fix --gemini # Gemini CLI
   aislop fix -p # Print prompt (agent-agnostic)
   
6. Verify with a final scan

   Confirm everything is resolved.

   aislop scan
   

Flags

-d, --verbose · boolean

Show detailed progress for each fix operation as it runs, including which files are modified and which rules are being resolved.

-f, --force · boolean

Run aggressive fixes in addition to standard ones. This includes dependency auditing, framework dependency alignment, and unused-file removal. Changes here are more likely to affect behaviour—review the diff before committing.

aislop fix -f

--safe · boolean

Restrict the run to reversible fixes only. Safe mode applies:

• Unused-import removal
• Import merging
• Narrative-comment removal
• Formatting

Anything that deletes code or rewrites behaviour—console removal, dead-code elimination, lint autofixes, unused-declaration pruning, and dependency changes—is skipped. A --safe run is designed to be “apply and commit” without review.

aislop fix --safe

-p, --prompt · boolean

Print an agent-ready prompt to stdout describing the remaining issues, without opening any specific agent. Use this flag when you want to paste the prompt into any tool or inspect it first.

aislop fix -p

Prompt handoff flags

When auto-fix can’t resolve an issue and you do not want the full aislop agent workflow, pass the remaining diagnostics to your coding agent. Each flag opens that agent and provides the structured prompt automatically. Use --prompt / -p if you prefer an agent-agnostic output you can paste anywhere.

Terminal agents

Flag	Agent
--claude	Claude Code
--codex	Codex CLI
--gemini	Gemini CLI
--kimi	Kimi Code CLI
--opencode	OpenCode
--aider	Aider
--goose	Goose
--pi	pi
--crush	Crush
--amp	Amp
--warp	Warp

Editor agents

Flag	Agent
--cursor	Cursor (copies prompt to clipboard)
--windsurf	Windsurf (copies prompt to clipboard)
--vscode	VS Code (copies prompt to clipboard)
--antigravity	Antigravity
--deep-agents	Deep Agents

Use --prompt (-p) to print the agent handoff prompt without opening any specific tool. You can then paste it into any agent, share it with a teammate, or inspect the diagnostics before deciding what to do next.

What —safe restricts

--safe is designed for situations where you want to improve the score with zero risk of introducing bugs. The table below shows what runs and what is skipped:

Fix type	--safe	Standard fix	fix -f
Unused-import removal	✅	✅	✅
Import merging	✅	✅	✅
Narrative-comment removal	✅	✅	✅
Formatting	✅	✅	✅
Console-log removal	—	✅	✅
Dead-code elimination	—	✅	✅
Lint autofixes	—	✅	✅
Unused-declaration pruning	—	✅	✅
Dependency auditing	—	—	✅
Framework alignment	—	—	✅
Unused-file removal	—	—	✅

Common examples

# See what's fixable before touching anything
aislop scan

# Apply only safe, reversible fixes
aislop fix --safe

# Standard auto-fix with detailed output
aislop fix -d

# Aggressive mode: deps, unused files, all autofixes
aislop fix -f

# Run the local repair workflow for remaining issues
aislop agent

# Or hand off remaining diagnostics to Claude Code
aislop fix --claude

# Print the agent prompt without opening any tool
aislop fix --prompt

# One-off run without installing
npx aislop@latest fix --safe