documentation / troubleshooting
Troubleshooting
Use the diagnostics below to distinguish configuration, provider, policy, and shell integration issues.
Provider errors
Check ai.provider, the endpoint, model, timeout, and the environment variable named by api_key_env. Use --provider mock to remove network and credential variables from an offline test.
Safety denial
A denial is expected for unknown, privileged, shell-interpreter, or invalid commands. Review the reason printed with the plan; changing a policy setting lowers the security posture and does not bypass command validation.
Shell integration
Confirm ashplug is on PATH, source the generated Bash or Zsh script again, and check the shell-specific startup file. The hook returns status 127 when the binary is unavailable and protects against recursion.
History
History is enabled by default and stored in SQLite. Use --no-history for an invocation that should remain ephemeral, or disable persistence in the [history] section.