Fixing Claude Code's Trailing-Dot Username Bug on macOS

macOS lets you put a period in your account short name. Mine was shahzaiba. — trailing dot included. That single character broke Claude Code's permission system for me in a way that no configuration could fix, and the eventual solution involved renaming the macOS account itself.

This post documents the root cause, why every workaround at the config level fails, and the rename procedure that finally fixed it. The full script and migration guide live in this gist, and the bug is tracked in anthropics/claude-code#54856.

The symptom

Every file operation — Read, Write, Edit, even trivial ones inside an explicitly allowed directory — triggered a permission prompt. Allow rules in settings.json like this had no effect:

{
  "permissions": {
    "allow": [
      "Write(/Users/shahzaiba./Documents/dev/**)",
      "Edit(/Users/shahzaiba./Documents/dev/**)"
    ]
  }
}

Approve, and the very next operation prompts again. bypassPermissions worked, but that's a sledgehammer — it disables the permission system entirely.

The root cause

Claude Code runs a path-pattern security scanner on tool inputs before evaluating permissions.allow. The scanner looks for suspicious path shapes, including Windows drive-letter patterns like C:\ and D./.

Now look at my home directory:

/Users/shahzaiba./Documents/dev

The segment a./ matches the scanner's <letter>./ heuristic. Every absolute path under my home directory looked like it was smuggling a Windows drive reference, so every operation got flagged.

The critical detail: because the scanner runs before the allow-list, there is no allow-rule syntax that can suppress it. The prompt isn't a permission decision being made against your rules — it's a security flag raised one layer earlier. I verified this on Claude Code 2.1.173; it still reproduces.

Why the only real fix is renaming the account

You can't escape your own home directory. Claude Code state, project paths, shell config — everything is anchored under /Users/<username>. As long as the username contains a period followed by a path separator, the scanner fires. So until the scanner is patched upstream, the fix is to remove the period from the account short name.

Renaming a macOS account sounds scary but is well-defined if you do it in the right order. The gist contains rename-account.sh, which automates it. The essentials:

1. Back up first. Time Machine or equivalent.
2. Fully log out of the affected account — Fast User Switching is not enough. With FileVault, unlocking the disk at boot auto-logs the account in, so log it out properly. The script checks and aborts otherwise.
3. Log into a second admin account and run sudo bash rename-account.sh.
4. Reboot and log in under the new name. Your password is unchanged — passwords, Keychain, and FileVault/SecureToken are tied to the account UUID, not the name.

Under the hood the script renames the home folder, updates NFSHomeDirectory and RecordName via dscl, refreshes admin group membership, and leaves a compatibility symlink /Users/olduser. -> /Users/newuser so any config still holding the old path keeps working until you sweep it.

One gotcha: if the mv on the home folder fails, that's TCC privacy protection, not a permissions error. Grant Terminal Full Disk Access in System Settings → Privacy & Security, reopen Terminal, and re-run — the script is idempotent about a half-done move.

Part two: getting your Claude Code sessions back

After the rename, Claude Code looks healthy — until you hit /resume and find every prior session gone. Nothing is lost; it's a keying problem.

Session transcripts live in ~/.claude/projects/ under directory names encoded from the absolute project path. /Users/shahzaiba./Documents/dev becomes -Users-shahzaiba--Documents-dev — note the double dash, because the period also encodes to -. After the rename, your projects resolve to new encoded names, so the old folders simply don't match anymore.

The migration is mechanical: for each old project directory, rewrite the path strings inside the transcripts, then rename the directory to the new encoding. One trap worth calling out — the directory names start with -, so naive tar or rm invocations parse them as flags. Prefix with ./:

cd ~/.claude/projects
tar -czf backup.tar.gz $(ls | grep '^-Users-olduser-' | sed 's|^|./|')

The gist's README walks through the full sequence, including ~/.claude.json and history.jsonl.

Takeaways

• Security scanners that run before user-configured allow-lists need an escape hatch. When a false positive fires on something as immutable as a home directory path, "approve it every time" is not a workflow.
• macOS account renames are safe when done from a second admin account with the target fully logged out — identity is keyed to the account UUID, not the short name.
• If your tooling encodes absolute paths into state keys, a username change is a migration, not a restart.

If you're hitting this bug, the gist has everything, and a 👍 on issue #54856 helps it get prioritized.