btw (version 1.2.0)

btw_task: Run a pre-formatted btw task

Description

Runs a btw task defined in a file with YAML frontmatter configuration and a markdown body containing the task prompt. The task file format is similar to btw.md files, with client and tool configuration in the frontmatter and the task instructions in the body.

Task File Format

Task files use the same format as btw.md files:

---
client:
  provider: anthropic
  model: claude-sonnet-4
tools: [docs, files]
---
Your task prompt here with {{ variable }} interpolation...

Template Variables

The task prompt body supports template variable interpolation using {{ variable }} syntax via ellmer::interpolate(). Pass named arguments to provide values for template variables:

btw_task("my-task.md", package_name = "dplyr", version = "1.1.0")

Additional Context

Unnamed arguments are treated as additional context and converted to text using btw(). This context is appended to the system prompt:

btw_task("analyze.md", dataset_name = "mtcars", mtcars, my_function)
#                      ^-- template var        ^-- additional context

Usage

btw_task(
  path,
  ...,
  client = NULL,
  mode = c("app", "console", "client", "tool")
)

Value

Depending on mode:

• "app": Returns the chat client invisibly after launching the app

• "console": Returns the chat client after console interaction

• "client": Returns the configured chat client

• "tool": Returns an ellmer::tool() object

Arguments

path

Path to the task file containing YAML configuration and prompt.

...

Named arguments become template variables for interpolation in the task prompt. Unnamed arguments are treated as additional context objects and converted to text via btw().

client

An ellmer::Chat client to override the task file's client configuration. If NULL, uses the client specified in the task file's YAML frontmatter, falling back to the default client resolution of btw_client().

mode

The execution mode for the task:

• "app": Launch interactive Shiny app (default)

• "console": Interactive console chat with ellmer::live_console()

• "client": Return configured ellmer::Chat client without running

• "tool": Return an ellmer::tool() object for programmatic use

See Also

Other task and agent functions: btw_task_create_btw_md(), btw_task_create_readme(), btw_task_create_skill()

Examples

# Create a simple task file
tmp_task_file <- tempfile(fileext = ".md")

cat(file = tmp_task_file, '---
client: anthropic/claude-sonnet-4-6
tools: [docs, files]
---

Analyze the {{ package_name }} package and create a summary.
')

# Task with template interpolation
btw_task(tmp_task_file, package_name = "dplyr", mode = "tool")

# Include additional context
btw_task(
  tmp_task_file,
  package_name = "ggplot2",
  mtcars,  # Additional context
  mode = "tool"
)