Install
CLI reference

Troubleshooting

Common issues and the fix for each. Start with blamely doctor — it prints the specific fix command for most problems.

blamely doctor is your friend

terminal
blamely doctor

Read-only. Tells you which piece is broken and prints the exact command to repair it. Run this first for anything weird.

No attribution bar after commit

  1. Confirm the daemon is up:
    terminal
    blamely status
  2. Confirm hooks are wired:
    terminal
    blamely doctor
  3. Make sure you edited files before committing. Blamely attributes edits it observed within a lookback window (8 hours by default).
  4. Check the daemon log:
    terminal
    tail -n 50 ~/.blamely/daemon.log

Daemon offline

terminal
blamely install

Re-registers the daemon with your platform’s service manager (launchd / systemd / Scheduled Task). Idempotent and safe.

If blamely status still shows offline:

terminal
blamely daemon    # run in foreground to see startup errors

Ctrl+C to stop it once you’ve seen the error.

blamely not found

The CLI is installed but PATH doesn’t include it. Either restart your terminal, or:

terminal
source ~/.zshrc       # zsh
source ~/.bashrc      # bash

The binary is always available at the stable path:

terminal
~/.blamely/bin/blamely status

You can use that path directly if the shell rc edit didn’t take effect (e.g., a custom shell init that ignores rc files).

AI tool not detected

terminal
blamely detect

Lists what Blamely sees. If your tool isn’t there, either it’s not installed in a standard location, or you installed it after Blamely. Fix:

terminal
blamely install     # idempotent, picks up newly-installed tools

All my lines show as Human

A few common causes:

  • The tool isn’t hooked. Run blamely detect and blamely doctor.
  • Inline Tab completion without a plugin. Cursor Tab and similar inline completions don’t fire hooks — only the editor plugin can see them. Install VS Code, Cursor, or JetBrains.
  • The edit happened more than 8 hours before the commit. That’s outside the default lookback window.
  • The work came from Devin Cloud. Cloud commits are attributed by the post-merge hook when you git pull them. If blamely doctor reports the post-merge script missing, re-run blamely install.

Stale per-repo hooks

If you used an older Blamely version, your repos may have .git/hooks/post-commit files left behind. Clean them up:

terminal
blamely repair --dry-run    # preview what would be removed
blamely repair              # actually remove them

The global core.hooksPath hook takes over.

Conflicting core.hooksPath

blamely install sets git config --global core.hooksPath to ~/.blamely/git-hooks/. If you have a different value for legitimate reasons (Husky, a corporate setup, etc.), check what’s there:

terminal
git config --global core.hooksPath

You can place your custom hooks into ~/.blamely/git-hooks/ and they’ll run alongside Blamely’s. Or, for a one-off repo, set core.hooksPath locally to override the global.

Editor plugin shows no data

  • Is the CLI installed? The plugin reads from ~/.blamely/db.sqlite — no CLI, no data.
  • Is the daemon running? blamely status. The plugin posts inline-completion events to the daemon; if it’s offline, those events are dropped (the plugin logs a single warning per 30s).
  • Are you in a git repo? The plugin only emits events for files inside a git working tree.

Database / state recovery

If something is badly broken and you want to start clean without losing notes:

terminal
blamely uninstall
rm -rf ~/.blamely
blamely install     # re-detect tools, register daemon, re-write hooks

Existing notes on commits are unaffected.

Need help?

  • blamely doctor — almost always tells you the fix.
  • ~/.blamely/daemon.log — the daemon’s running log.
  • GitHub Issues — for bugs and feature requests.

Next

Something unclear or wrong? Tell us.