Task: Initialize Project Context File

Create a comprehensive context btw.md or AGENTS.md file for your project. If launched in app or console mode, this task will start an interactive chat session to guide you through the process of creating a context file.

This task focuses on documenting project context for developers and agents. See btw_client() for additional details about the format and usage of the btw.md context file, including choosing the default LLM provider and model or the default set of tools to use with btw_client().

Usage

btw_task_create_btw_md(
  ...,
  path = "btw.md",
  client = NULL,
  mode = c("app", "console", "client", "tool")
)

Arguments

...

Additional context to provide to the AI. This can be any text or R objects that can be converted to text using btw().

path

The path to the context file to create. Defaults to btw.md.

client

An ellmer::Chat client or a provider/model string to be passed to ellmer::chat() to create a 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.

mode

The mode to run the task in, which affects what is returned from this function. "app" and "console" modes launch interactive sessions, while "client" and "tool" modes return objects for programmatic use.

Value

When mode is "app" or "console", this function launches an interactive session in the browser or the R console, respectively. The ellmer chat object with the conversation history is returned invisibly when the session ends.

When mode is "client", this function returns the configured ellmer chat client object. When mode is "tool", this function returns an ellmer tool object that can be used in other chat instances.

See also

Other task and agent functions: btw_task_create_readme()

Examples

withr::with_envvar(list(ANTHROPIC_API_KEY = "example"), {
  btw_task_create_btw_md(mode = "tool", client = "anthropic")
})
#> Using model = "claude-sonnet-4-20250514".
#> Warning: file("") only supports open = "w+" and open = "w+b": using the former
#> # <ellmer::ToolDef> btw_task_create_btw_md(prompt, path)
#> # @name: btw_task_create_btw_md
#> # @description: Create a comprehensive context file for your project.
#> # @convert: TRUE
#> #
#> function (prompt, path = NULL) 
#> {
#>     sys_prompt <- ellmer::interpolate(this_client$get_system_prompt(), 
#>         path_summary_file = path %||% path_default)
#>     sys_prompt <- paste0(sys_prompt, "\n\n---\n\n", "YOU ARE NOW OPERATING IN TOOL MODE. ", 
#>         "The user cannot respond directly to you. ", "Because you cannot talk to the user, you will need to make your own decisions using the information available to you and the best of your abilities. ", 
#>         "You may do additional file exploration if needed.")
#>     this_client <- client$clone()
#>     this_client$set_system_prompt(sys_prompt)
#>     this_client$chat(prompt)
#> }
#> <bytecode: 0x556b21752b88>
#> <environment: 0x556b217593d8>