Getting started with ellmercodex

Versión en español: vignette("ellmercodex-es", package = "ellmercodex").

ellmercodex lets you use your ChatGPT plan from R as an ellmer provider. You sign in once with your ChatGPT account, and chat_codex() gives you an ordinary ellmer Chat object: no API key, and no Codex CLI.

It uses OpenAI’s documented “Sign in with ChatGPT” flow for open-source, locally hosted apps, and the public Responses API. ChatGPT plan usage is an OpenAI preview, and ellmercodex is not affiliated with or endorsed by OpenAI.

The examples in this article need a signed-in session, so they are not run when the article is built. The output shown comes from a real session.

Check your setup

library(ellmercodex)

codex_available()
#> [1] TRUE

codex_available() checks that the installed dependencies and the supported ellmer version are in place. It does not read your credentials or contact the network, so TRUE does not guarantee that a request will succeed.

Sign in

codex_login()

codex_login() opens your browser, where you choose a ChatGPT account and workspace and allow ChatGPT plan usage. The credential is saved privately and refreshed automatically, so you only need to do this once per machine. vignette("authentication") covers where it is stored and how to sign out or switch accounts.

Your first chat

chat <- chat_codex(model = "gpt-6-luna", effort = "low")
chat$chat("Hello from R")
#> Hello! What are you working on in R?

Each $chat() call adds to the conversation history, so follow-up questions have the earlier context. Use $stream() to see the answer as it is generated:

chat$stream("Give me three ideas for naming an R package.")

If you leave out model, chat_codex() picks a usable model from your account’s catalog. vignette("models") explains how to list models, pick one, and set the reasoning effort.

It is an ellmer Chat

chat_codex() returns a regular ellmer Chat, so the ellmer documentation applies. These work as they do with any other provider:

  • Structured data with $chat_structured(): see ellmer’s structured data article.
  • Tool calling with $register_tool(): see tool/function calling.
  • Streaming and async with $stream(), $chat_async(), and $stream_async(), including cancellation with ellmer::stream_controller(): see streaming and async APIs.
  • Images and PDFs with ellmer::content_image_file(), ellmer::content_pdf_file(), and friends.
  • Cloning and history with $clone(), $get_turns(), and $set_turns(): see programming with ellmer.

vignette("text-analysis") puts structured data and tools together on a real text-analysis task.

A few things are different because of how ChatGPT plan usage works: parallel_chat() and batch_chat() are not supported, and arguments such as temperature and max_tokens are rejected. vignette("errors-and-limits") lists them and shows how to handle errors.

Learn more

  • vignette("authentication"): signing in, stored credentials, and signing out.
  • vignette("models"): models and reasoning effort.
  • vignette("text-analysis"): structured data and tools on real text.
  • vignette("errors-and-limits"): condition classes, plan limits, and what is not supported.