Troubleshooting
"I'm not recognised" / warnings say "unknown"
fixlock identifies you by git config user.email. Check:
bash
git config user.email
npx fixlock teamAsk your lead to add the email you actually commit with (fixlock team add … --email a@x.com,b@y.com). For a one-off, set FIXLOCK_USER=you@company.com.
Claude Code doesn't show any fixlock prompt
.claude/settings.jsonmust contain a fixlock hook command:npx --no-install fixlock hook claude(installed with npm),npx -y @abinandhmj/fixlock@<version> hook claude(not installed), orfixlock hook claude(installed with pip). Runfixlock install-claude-hookto rewrite it.- With
npx --no-install, fixlock must be installed in the project (npm i -D @abinandhmj/fixlock); it won't download it. Withfixlock hook claude, thefixlockcommand must be on your PATH (pipx install fixlock). - Restart Claude Code after changing settings.
- You won't be prompted for locks you own, your own uncommitted work, or edits under
minLines. - Test the hook by hand:bash
echo '{"tool_name":"Write","cwd":".","tool_input":{"file_path":"src/x.ts","content":""}}' | npx fixlock hook claude
fixlock: command not found
The repo was set up with the pip-installed command ("launcher": "fixlock" in .fixlock/config.json), so its hooks call fixlock directly.
- Install it once:
pipx install fixlock(oruv tool install fixlock). - With pipx, run
pipx ensurepathand open a new terminal iffixlockstill isn't found. - Prefer npx on your machine? Set
FIXLOCK_LAUNCHER=npxin your environment. To switch the whole repo, changelauncherin.fixlock/config.jsonand runfixlock sync(see Configuration).
Commit warning or auto-lock doesn't run
- Run
npx fixlock install-hookon each machine. Git hooks aren't shared through the repo. - If your project uses Husky or another hook manager, it may replace
.git/hooks. Add these lines to its hooks instead:- pre-commit:
npx --no-install fixlock check --staged || true - post-commit:
[ -n "$FIXLOCK_IN_HOOK" ] || FIXLOCK_IN_HOOK=1 npx --no-install fixlock autolock --commit-result --quiet || true
- pre-commit:
- Auto-lock only reacts to fix/feature messages.
chore:,docs:and similar are skipped on purpose.
CI blocks even after the owner approved
GITHUB_TOKENmust be set and able to read pull requests.- The approver's GitHub username in
.fixlock/config.jsonmust match their GitHub login. - A later "Request changes" from the same person cancels their approval.
- Re-run the check after approval (GitHub: the
pull_request_reviewtrigger; Jenkins: re-run the job). - The output line
! Could not read PR approvals: …explains API errors.
CI says "Could not diff against origin/main"
The checkout is shallow or main wasn't fetched. Use fetch-depth: 0 (GitHub Actions) or git fetch origin main before the check.
Too many false alarms
- Lock fewer, more specific lines:
fixlock remove FIX-00x, thenfixlock markjust the key lines. - Raise
stableCode.minLines, or setstableCode.onEdittowarn. - Set
autoLock.lockFeaturestofalse, or lowerautoLock.maxLines.
Windows
- Use PowerShell or Command Prompt; Git for Windows runs the git hooks with its own shell.
'bash' is not recognized: you have an old copy of the package. Version 0.2.0 and later run tests with Node.- Paths in locks are stored with
/, so locks made on Windows work on macOS/Linux and in CI.
Publishing (maintainers)
403 … Package name too similar: npm blocks names close to existing ones. The package is published under the scope@abinandhmj/fixlock.- Scoped packages need
npm publish --access=public. npm testmust printE2E PASSandTRACKERS PASSbefore publishing.
Tracker issue didn't move
- Check the token env var is set where the command runs (your shell for
mark, CI secrets forcheck --notify). - Status names must match exactly what exists in Linear / ClickUp / Notion.
- The command output shows
tracker: … sync failed: <reason>.