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

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)

Which search engine is best for R-related questions?

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.

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()

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:

1. You’ll need to be logged in to that service in your browser
2. You don’t need to manage API keys in R
3. 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.

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").

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)

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:

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

This could be due to several issues:

1. Check if you’re in an interactive R session (the browser won’t open in non-interactive sessions)
2. Make sure your system has a default browser configured
3. Try setting a longer delay: options(searcher.launch_delay = 1)
4. 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:

1. Using a more specific prompt:

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

2. Setting a system-level prompt:

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

3. 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.