Skip to contents

Create a btw-enhanced ellmer chat client

Source: R/btw_client.R, R/btw_client_app.R
btw_client.Rd

Creates an ellmer::Chat client, enhanced with the tools from btw_tools(). Use btw_client() to create the chat client for general or interactive use at the console, or btw_app() to create a chat client and launch a Shiny app for chatting with a btw-enhanced LLM in your local workspace.

Project Context

You can keep track of project-specific rules, guidance and context by adding a btw.md file in your project directory. Any time you start a chat client with btw_client() or launch a chat session with btw_app(), btw will automatically find and include the contents of the btw.md file in your chat.

Use btw.md to inform the LLM of your preferred code style, to provide domain-specific terminology or definitions, to establish project documentation, goals and constraints, to include reference materials such or technical specifications, or more. Storing this kind of information in btw.md may help you avoid repeating yourself and can be used to maintain coherence across many chat sessions.

The btw.md file, when present, is included as part of the system prompt for your chat conversation. You can structure the file in any way you wish.

You can also use the btw.md file to choose default chat settings for your project in a YAML block at the top of the file. In this YAML block you can choose settings for the default ellmer chat client, e.g. provider, model, as well as choose with btw tools to use in btw_client() or btw_app(). provider chooses the ellmer::chat_*() function, e.g. provider: openai or provider: chat_openai to use ellmer::chat_openai(). tools chooses which btw tools are included in the chat, and all other values are passed to the ellmer::chat_*() constructor, e.g. model: gpt-4o, seed: 42, or `echo: all“.

Here's an example btw.md file:

---
client:
  provider: claude
  model: claude-3-7-sonnet-20250219
tools: [data, docs, environment]
---

Follow these important style rules for any R code in this project:

* Prefer solutions that use {tidyverse}
* Always use `<-` for assignment
* Always use the native base-R pipe `|>` for piped expressions

You can hide parts of the btw.md file from the system prompt by wrapping them in HTML <!-- HIDE --> and <!-- /HIDE --> comment tags. A single <!-- HIDE --> comment tag will hide all content after it until the next <!-- /HIDE --> tag, or the end of the file. This is particularly useful when your system prompt contains notes to yourself or future tasks that you do not want to be included in the system prompt.

For project-specific configuration, store your btw.md file in the root of your project directory. For global configuration, you can maintain a btw.md file in your home directory (at btw.md or .config/btw/btw.md in your home directory, using fs::path_home()). This file will be used by default when a project-specific btw.md file is not found.

Client Options

  • btw.client: The ellmer::Chat client to use as the basis for new btw_client() or btw_app() chats.

  • btw.tools: The btw tools to include by default when starting a new btw chat, see btw_tools() for details.

Usage

btw_client(..., client = NULL, tools = NULL, path_btw = NULL)

btw_app(..., client = NULL, tools = NULL, path_btw = NULL)

Arguments

...

Additional arguments are ignored. ... are included for future feature expansion.

client

An ellmer::Chat client, defaults to ellmer::chat_anthropic(). You can use the btw.client option to set a default client for new btw_client() calls, or use a btw.md project file for default chat client settings, like provider and model. We check the client argument, then the btw.client R option, and finally the btw.md project file, using only the client definition from the first of these that is available.

tools

A list of tools to include in the chat, defaults to btw_tools(). Join btw_tools() with additional tools defined by ellmer::tool() to include additional tools in the chat client. Alternatively, you can use a character values to refer to specific btw tools by name or by group. For example, use tools = "docs" to include only the documentation related tools, or tools = c("env", "docs") to include the environment and documentation tools, and so on. You can also refer to btw tools by name, e.g. tools = "btw_tool_docs_help_page" or alternatively in the shorter form tools = "docs_help_page". Finally, set tools = FALSE to skip registering btw tools with the chat client.

path_btw

A path to a btw.md project context file. If NULL, btw will find a project-specific btw.md file in the parents of the current working directory.

Value

Returns an ellmer::Chat object with additional tools registered from btw_tools(). btw_app() returns the chat object invisibly, and the chat object with the messages added during the chat session.

Functions

  • btw_client(): Create a btw-enhanced ellmer::Chat client

  • btw_app(): Create a btw-enhanced client and launch a Shiny app to chat

Examples

if (FALSE) { # rlang::is_interactive()
withr::local_options(list(
  btw.client = ellmer::chat_ollama(model="llama3.1:8b")
))

chat <- btw_client()
chat$chat("How can I replace `stop()` calls with functions from the cli package?")
}