Frequently Asked Questions (FAQ)

Frequently Asked Questions

This vignette addresses common questions about using the searcher package. If you have a question not covered here, please consider opening an issue on GitHub.

General Questions

What is the `searcher` package?

The searcher package provides a search and query interface directly inside R. It allows you to quickly search or inquiry about error messages, code examples, or any query across multiple platforms including search engines, developer communities, code repositories, and AI assistants.

How do I install the package?

# From CRAN (stable version)
install.packages("searcher")

# From GitHub (development version)
if(!requireNamespace("remotes")) { install.packages("remotes") }
remotes::install_github("coatless-rpkg/searcher")

Why would I use `searcher` instead of manually searching in a browser?

searcher offers several advantages:

Streamlines the workflow by allowing you to search directly from R
Automatically formats queries to be R-specific
Can automatically search error messages
Provides direct integration with AI assistants with R-specific prompts
Saves time by not having to copy/paste errors or switch contexts

Which platforms does `searcher` support?

The package supports multiple types of platforms:

Search Engines
- Google, Bing, DuckDuckGo, Startpage, Ecosia, Qwant, Brave, Kagi, Rseek
AI Assistants
- ChatGPT, Claude, Perplexity, Mistral, Microsoft (Bing)’s Copilot, Grok, Meta AI
Developer Communities
- StackOverflow, Posit Community, Twitter/X, Mastodon, BlueSky
Code Repositories
- GitHub, BitBucket, grep.app

Search Functionality

How do I search for a specific term?

Simply use any of the search functions with your query:

# Search Google
search_google("ggplot2 themes")

# Search StackOverflow
search_stackoverflow("dplyr filter")

# Search GitHub
search_github("shiny dashboard")

How do I ensure my search results are R-specific?

By default, all search functions append R-specific terms to your queries. This behavior is controlled by the rlang parameter which is set to TRUE by default. If you want more general results, set rlang = FALSE:

# R-specific results
search_google("linear regression")

# General results not limited to R
search_google("linear regression", rlang = FALSE)

Different platforms have different strengths:

Rseek (search_rseek()) is a specialized search engine for R content
StackOverflow (search_stackoverflow()) is excellent for specific error messages and programming questions
GitHub (search_github()) is useful for package-specific issues
Posit Community (search_posit_community()) is great for questions about RStudio, Shiny, and other Posit products

For general searches, Google often provides the most comprehensive results, but you might prefer privacy-focused alternatives like DuckDuckGo or Brave.

Working with Errors

How do I search for an error message?

If you’ve just encountered an error, all search functions will use the last error message as the default query if you don’t specify one:

# This will search the last error message on Google
search_google()

# This will search the last error message on StackOverflow
search_stackoverflow()

Can I automatically search errors when they occur?

Yes, you can set the error option to use one of the search functions:

# Automatically search errors on Google
options(error = searcher("google"))

# Automatically search errors on StackOverflow
options(error = search_stackoverflow)

# Automatically send errors to Claude AI
options(error = ask_claude)

Is there a way to search warnings too?

The searcher package itself doesn’t directly handle warnings, but the companion package errorist provides this functionality:

# Install errorist
install.packages("errorist")

# Set up errorist to search both errors and warnings
errorist::errorist_enable()

AI Assistant Integration

How do I use AI assistants with `searcher`?

The package provides dedicated functions for interacting with AI assistants:

# Ask ChatGPT
ask_chatgpt("How do I create a violin plot in ggplot2?")

# Ask Claude
ask_claude("Explain the difference between lapply and sapply")

# Ask Perplexity
ask_perplexity("What's the best approach for time series forecasting in R?")

Do I need API keys to use the AI features?

No. The AI search functions open a browser tab with your query pre-filled on the respective AI service’s web interface. This means:

You’ll need to be logged in to that service in your browser
You don’t need to manage API keys in R
Any usage limits will be based on your account with that service

How do I customize how AI assistants respond to my queries?

You can customize AI responses using prompts in two ways:

1. Per-call prompts:

ask_chatgpt("How to merge data frames?", 
            prompt = "Show examples using both base R and dplyr:")

2. Default prompts via options:

options(searcher.claude_prompt = "As an R expert, provide clear code examples:")

# Now all Claude queries will use this prompt
ask_claude("How to handle missing data?")

3. System-level prompts:

# Use a built-in prompt
ai_prompt("debugging")
# Now all AI assistants will use the debugging prompt
ask_claude("Error: object 'mtcrs' not found")


# Set a system-level prompt
ai_prompt("As an R educator, explain this concept in detail:")

# Now all AI assistants will use this prompt
ask_chatgpt("What is the tidyverse?")

See vignette("using-ai-assistants-with-searcher", "searcher") for more details on effective prompting.

Prompt Management

What is the prompt management system?

The prompt management system in searcher allows you to create, store, and apply sophisticated prompts when working with AI assistants. This helps you get more consistent and helpful responses.

How do I use the built-in prompts?

The package comes with several pre-defined prompts for different scenarios:

# List available prompts
ai_prompt_list()

# Set the "debugging" prompt as active
ai_prompt("debugging")

# Now use any AI assistant with this prompt
ask_claude("Error: object 'mtcrs' not found")

Can I create my own prompts?

Yes, you can either use custom prompt text directly or add it to the prompt library:

# Use custom text directly
ai_prompt("As an R package developer, explain this error in detail:")

# Add to the prompt library
ai_prompt_register(
  "tidyverse_expert",
  "As a tidyverse expert, provide modern data manipulation solutions:"
)

# Use your registered prompt
ai_prompt("tidyverse_expert")

For more details, see vignette("managing-ai-prompts", "searcher").

Customization

How do I customize the default behavior of `searcher`?

You can set various options to customize the package behavior:

# In your .Rprofile or at the start of your session
options(
  # Launch browser after a delay (in seconds)
  searcher.launch_delay = 0.2,
  
  # Use RStudio's viewer pane instead of a browser
  searcher.use_rstudio_viewer = TRUE,
  
  # Default keyword suffix (base or tidyverse)
  searcher.default_keyword = "tidyverse",
  
  # Default prompts for AI services
  searcher.chatgpt_prompt = "You are an R educator...",
  searcher.claude_prompt = "As an R expert..."
)

How do I change the default search keyword from “base” to “tidyverse”?

You can change the default keyword suffix used in searches by setting the searcher.default_keyword option:

# In your .Rprofile or at the start of your session
options(searcher.default_keyword = "tidyverse")

This will modify the keywords appended to your searches to target tidyverse-related content instead of base R.

How can I reduce or increase the delay before the browser opens?

By default, there’s a 0.5-second delay before opening a browser. You can adjust this:

# Shorter delay (0.2 seconds)
options(searcher.launch_delay = 0.2)

# No delay
options(searcher.launch_delay = 0)

# Longer delay (1 second)
options(searcher.launch_delay = 1)

Comparing AI Solutions

How does `searcher`’s AI assistant integration differ from the `ellmer` package?

Both searcher and ellmer provide ways to integrate AI assistance into your R workflow, but they take different approaches and have different strengths:

Interface Differences

searcher: Opens a web browser with your query pre-filled in the AI service’s web interface. This means:

No API keys or tokens needed in R
Utilizes the full web interface capabilities
Works with multiple AI services (ChatGPT, Claude, Perplexity, etc.)
Requires browser access and being logged in to the services

ellmer: Uses API connections to interact with AI models directly from R. This generally means:

Requires API keys and managing tokens
Results are returned directly to your R console/environment
More programmatic control over interactions
Works without a browser and in non-interactive sessions

Use Case Differences

Use searcher when:
- You prefer a visual interface for complex queries
- You want to use multiple different AI services without managing API keys
- You want to take advantage of special features in the web interfaces
- You’re asking exploratory questions or conducting research
Use ellmer when:
- You need programmatic access to AI responses
- You want to integrate AI responses directly into R scripts or applications
- You need to process many queries in batch
- You’re working in environments without browser access

Prompt Management

searcher: Offers a prompt management system for web interfaces
ellmer: Typically provides direct control over prompts in API calls

Complementary Usage

These packages can be complementary rather than competitive:

Use searcher for exploratory work, debugging, and research
Use ellmer for production code, reproducible workflows, and batch processing

If you’re building AI capabilities into an R package or application, ellmer’s API approach may be more suitable. For interactive use during data analysis or debugging, searcher’s browser approach may be more convenient.

Troubleshooting

My browser doesn’t open when I use a search function. What’s wrong?

This could be due to several issues:

Check if you’re in an interactive R session (the browser won’t open in non-interactive sessions)
Make sure your system has a default browser configured
Try setting a longer delay: options(searcher.launch_delay = 1)
If using RStudio Server, browser support may be limited

How do I search an error that’s not the most recent one?

If you want to search a specific error rather than the most recent one, you need to explicitly provide the error message:

search_google("Error: object 'specific_error' not found")

The AI assistant isn’t giving me R-specific answers. How do I fix this?

If the AI responses aren’t focused on R, try:

Using a more specific prompt:

ask_claude("How to join tables?", prompt = "I'm specifically asking about R dplyr joins.")

Setting a system-level prompt:

ai_prompt("As an R programming expert, all my questions are about R unless specified otherwise.")

Including “in R” explicitly in your queries:
```
ask_chatgpt("How to join tables in R?")
```

Can I use `searcher` in non-interactive scripts?

Yes, but the browser opening functionality will be disabled in non-interactive sessions. The functions will still return the search URLs, which can be useful in logs or notifications.

James Joseph Balamuta

2025-05-27