Skip to main content
charter fix has a hard guarantee: it never mutates a file without showing you the diff first. This guide makes sure you never skip that step.
Never run charter fix without --dry-run first. The diff is the contract — read it before accepting it. Applying a fix you haven’t reviewed defeats the purpose of a diff-first tool.
1

Always dry-run first

Before writing anything, preview every change:
Charter prints a unified diff for each affected file. Each hunk shows you the exact before/after — the file path, the rule being addressed, and whether the change is a create, append, or replacement.Read every diff. If a diff looks wrong for your repo, stop and make the change manually instead.
2

Understand what you're applying

Charter’s safe fixers are narrow by design. Here’s exactly what each one does:
Creates AGENTS.md using a template populated with your detected language, CI platform, and toolchain. The template is a starting point — review it and fill in repo-specific context before committing. Charter will not overwrite an existing AGENTS.md.
Appends agent artifact patterns to your .gitignore (.charter/, *.charter-session, .claude/local/, .cursor/cache/). Review before committing to confirm no existing entries conflict and no paths you intend to track are being excluded.
Creates .github/workflows/charter.yaml with a standard Charter gate workflow. Check the threshold value and verify the actions/checkout SHA pin matches the version you want before committing.
Updates floating @latest, semver ranges, or missing version pins in your MCP config to the exact version from Charter’s catalog. Verify the resolved version is the one you want — especially for packages where the catalog version may lag the latest release.
charter fix does not delete files, silently mutate files, auto-fix secret findings, or auto-fix rules outside the four safe fixers above. That narrow scope is intentional.
3

Apply the fixes

Once the diffs look right, apply:
When Charter updates an existing file, it writes the prior version to .charter/backups/<timestamp>/ before making any changes. Create-only operations (new files) don’t produce a backup because there’s nothing to restore.
4

Re-scan to verify

Never assume a fix is good just because the diff looked right. Always verify:
Confirm:
  • the targeted finding no longer appears in the active findings list
  • the score moved in the right direction
  • the fix didn’t reveal a new problem elsewhere
5

Commit the result

Review the staged changes with git diff --staged before committing:

​
Recovery

If you applied a fix and want to revert, Charter’s backups are in .charter/backups/:
You can also use git checkout if the change has been staged but not committed:
Use a manual edit instead of charter fix when:
  • the file already exists and the repair needs repo-specific judgment
  • the change is outside the four safe fixers
  • the finding is about secrets or another manual-only rule
  • the generated template content needs substantial customization before it would be accurate
charter fix is best when the safe path is obvious and mechanical.

​
Next steps

Fix Engine

Why only four rules have fixers, and why secrets never do.

charter fix

Every flag the fix command accepts.

Suppress a Finding

When a finding can’t be fixed, record a governed exception.

Add Charter to an Existing Repo

The full adoption loop from first scan to committed baseline.