term.works

Docs · For developers

Troubleshooting

Fixes for the most common issues: the hook not firing, virtualenvs, CI environments, and refreshing after an update.

Most issues come down to the shell hook not being loaded in your current session.

I never see any opportunities

  1. Start a new shell (or source ~/.zshrc / ~/.bashrc). The hook only applies to shells started after install.
  2. Check it's enabled: termworks status. Re-enable with termworks enable.
  3. Confirm you're linked: termworks login.
  4. Opportunities are intentionally infrequent and capped, and only show on relevant commands — some quiet stretches are normal.

Does it work in Python virtual environments?

Yes. Activating a venv doesn't disturb the hook, and TermWorks classifies both activated and path-invoked interpreters (e.g. .venv/bin/python) plus the venv toolchain (virtualenv, pyenv, conda, pipenv, uv, poetry, …).

What about CI?

TermWorks detects CI and non-interactive shells and stays silent — it never shows opportunities or earns there.

I updated but nothing changed

The hook auto-refreshes on termworks update; just start a new shell so the refreshed hook is re-sourced.

Still stuck?

Run termworks status and email hello@term.works with the output.

Still need help? hello@term.works