Skip to main content

​
Troubleshooting

​
Capture isn’t working

Check status first:
If it shows Capture active but no events are appearing, the shell hook may not be loaded. Reload your shell:
Then run a command and check:
Enable debug mode to see what the capture process is doing:

​
Shell hook is not installed

If workscribe init didn’t detect your shell or the hook is missing:
Re-running init is safe — it skips steps already completed and re-attempts the hook install. If you’re using a non-standard shell (fish, nushell), the hook is not currently supported. You can manually trigger capture:
Windows is not supported. The shell hook requires zsh or bash. If you’re on Windows, use WSL2 with zsh or bash — Workscribe works normally inside WSL2.

​
Tab completion isn’t working

Shell completions are a snapshot taken at the time you ran workscribe init — upgrading the npm package doesn’t update an already-installed ~/.workscribe/completion.* file on its own. If completions stop working or are missing commands after an upgrade, refresh the cache file directly:
Then reload your shell:
You can also re-run workscribe init and accept the completions prompt again — as of v1.14.2 this is safe to repeat and won’t duplicate lines in your rc file.

​
”No activity captured for today”

Either no events have been captured yet, or all commands ran were on the ignore list. Check:
If events exist but workscribe summary shows nothing, check the date:

​
Summary looks wrong or generic

Wrong project name: The project name comes from the git remote URL, package.json, or folder name. If the folder name doesn’t match the repo, set an override:
Summary has no heading: This shouldn’t happen — headings are generated from your data, not the AI. If you’re seeing this, run workscribe --version to check your installed version. Bullet points are off-topic: Try --fresh to regenerate without cache:
For local models (Ollama), try a larger model:

​
“AI provider not configured”

​
Ollama: “connection refused”

Ollama isn’t running. Start it:
And ensure the model is pulled:

​
API key errors (401 / 403)

Confirm a key is stored (output is masked for security):
If no key is set or you need to replace it:

​
Webhook not posting

Test your webhook URL directly:
If that works but --slack doesn’t, confirm the webhook is set (output is masked):

​
Database errors

If you see SQLite errors, the database may be corrupted. The safest fix:
This loses captured history but config is unaffected.

​
Uninstalling

Run the uninstall command first — it removes the shell hook from your rc file before the binary is deleted:
Then remove the package:
Note: From v1.8.0 onwards, npm uninstall -g removes the shell hook automatically via a preuninstall lifecycle script. Running workscribe uninstall first is still recommended if you want to be prompted about deleting your data.

​
Shell errors after uninstalling (workscribe_precmd: unknown function)

If you uninstalled the package without running workscribe uninstall first, the shell hook block may still be in your rc file. The binary is gone so you can’t use the CLI to clean it up — use this one-liner instead. zsh:
bash:
Or open the file in any editor and manually delete everything between (and including) the two lines:
After removing the block, restart your terminal or run source ~/.zshrc (or ~/.bashrc).