Frequently Asked Questions

General

What shells are supported?

Whisp supports:

• Bash (4.0+)
• Zsh (5.0+)
• Fish (3.0+)

The CLI itself works in any terminal, but shell shortcuts (,, ,,, etc.) require the shell integration to be sourced.

What operating systems are supported?

• Linux — Full support
• macOS — Full support
• Windows — Not currently supported (WSL works)

Is whisp free to use?

Whisp itself is free and open source. However, most AI providers (OpenAI, Anthropic, Gemini, Cerebras) require paid API access.

Free options:

• Ollama — Run models locally at no cost (requires GPU for good performance)
• Some providers offer free tiers with limited usage

How much does it cost?

Typical costs per 1000 queries (rough estimates):

Check whisp metrics to see your actual token usage.

Privacy & Security

Is my data sent to the cloud?

With cloud providers (OpenAI, Anthropic, etc.): Yes, your queries and command context are sent to the provider's API. This includes:

• Your natural language query
• Current working directory
• Recent command context (for error recovery)
• Stderr output (for error recovery)

With Ollama: No, everything stays on your machine.

Are my API keys safe?

Whisp stores API keys in ~/.config/whisp/config.toml. For security:

1. The file should have 600 permissions (owner read/write only)
2. Whisp warns if permissions are too permissive
3. Keys can also be set via environment variables (never stored on disk)

Does whisp log my commands?

Whisp maintains a local history at ~/.whisp/history.jsonl for features like ,/ (search). This file:

• Never leaves your machine
• Contains only commands you ran through whisp
• Can be cleared with whisp history clear

Sensitive data (API keys, passwords) is automatically redacted before storage.

Features

Can I use multiple providers?

Yes! You can configure all providers and switch between them:

# Configure during setup
whisp init

# Switch providers
whisp config set provider anthropic
whisp config set provider ollama

Each provider can have its own model setting.

Can I use whisp offline?

Yes, with Ollama:

# Set up Ollama
whisp config set provider ollama

# Ensure you have a model downloaded
ollama pull llama3.2

# Works offline after model is downloaded

Cloud providers (OpenAI, Anthropic, etc.) require internet access.

What's the difference between , and whisp chat?

Use , for quick command generation. Use chat for complex tasks requiring back-and-forth.

How do I change the AI model?

# See current model
whisp config get model

# Change model
whisp config set model gpt-4o

# Change model for specific provider (in config file)
# ~/.config/whisp/config.toml
[providers.openai]
model = "gpt-4o-mini"

Does whisp work in scripts?

The CLI works in scripts, but shell shortcuts (,, ,,) are designed for interactive use. For scripts:

# Use the CLI directly
result=$(whisp shell query "find files larger than 100MB")

# Or send requests to the daemon
echo '{"type":"query","query":"list git branches"}' | nc -U /tmp/whisp.sock

Troubleshooting

Why do I see "Daemon not running"?

The whisp daemon needs to be running for AI features. Start it with:

whisp start

For auto-start on login, use:

whisp install

Why are responses slow?

Common causes:

1. Network latency — Try a local provider (Ollama)
2. Large model — Switch to a faster model (gpt-4o-mini vs gpt-4o)
3. Rate limiting — You may be hitting API limits

Check whisp health for response time metrics.

Why doesn't error recovery work?

Error recovery requires:

1. Daemon running (whisp status)
2. Shell integration sourced
3. Command that actually fails (exit code != 0)

Some commands are excluded (those starting with whisp or ,).

How do I reset everything?

# Stop daemon
whisp stop

# Remove config
rm -rf ~/.config/whisp

# Remove history
rm -rf ~/.whisp

# Remove service (if installed)
whisp uninstall

# Start fresh
whisp init

Customization

Can I customize the shell shortcuts?

The shortcuts (,, ,,, etc.) are defined in the shell integration files. You can modify them in:

• Bash: ~/.config/whisp/shell/whisp.bash
• Zsh: ~/.config/whisp/shell/whisp.zsh
• Fish: ~/.config/whisp/shell/whisp.fish

However, updates may overwrite your changes.

Can I use a custom API endpoint?

Yes, for self-hosted or proxy setups:

# ~/.config/whisp/config.toml
[providers.openai]
base_url = "https://my-proxy.example.com/v1"
api_key = "..."

Can I add my own AI provider?

Not currently. Whisp supports:

• OpenAI (and OpenAI-compatible APIs via base_url)
• Anthropic
• Google Gemini
• Cerebras
• Ollama

For unsupported providers, you might be able to use an OpenAI-compatible proxy.

Contributing

How do I report a bug?

Open an issue at github.com/n-f9/whisp/issues with:

1. Output of whisp doctor
2. Your OS and shell version
3. Steps to reproduce

How do I request a feature?

Open a GitHub issue with the "feature request" label. Describe:

• What you want to do
• Why current features don't meet your needs
• How you'd expect it to work

Can I contribute code?

Yes! See the Contributing Guide for:

• Development setup
• Code style guidelines
• Pull request process