rift

A minimal CLI coding harness built around the OpenAI Responses API.

Rift keeps the local harness small: it sends your prompt and a few local tools to the model, executes requested tool calls, then continues the same Responses API thread with previous_response_id until the model returns a final answer.

Install / build

npm install
npm test
npm run build

Run locally:

node dist/rift.js --help

The build uses esbuild to bundle and minify the CLI into a single file at dist/rift.js. If installed as a package, the binary is rift.

Project layout

Code and tests are grouped together by feature, so each area can be changed and verified in one place:

src/
  agent/   OpenAI agent and local tools
  cli/     command-line option parsing
  config/  configuration persistence
  input/   command-line and piped prompt input
  session/ session persistence and selection
  main.ts  command dispatch and process entry point

Configuration

Rift stores settings in ~/.config/rift/config.json by default, or under $XDG_CONFIG_HOME/rift/config.json.

rift config set api-key sk-...
rift config set model gpt-5-mini
rift config set web-search true
rift config get
rift config path

You can also provide the API key with OPENAI_API_KEY; the environment variable takes precedence over the saved key.

ChatGPT subscription (Plus/Pro)

Instead of an API key, Rift can bill runs to your ChatGPT subscription, the same way pi and opencode do: sign in once and Rift handles OAuth tokens itself. No Codex CLI needed. An API key still takes precedence when one is set.

rift login              # browser sign-in (opens ChatGPT)
rift login --device     # headless: enter a code on another device
rift auth status
rift logout
rift "fix the tests"

The login is stored as user-only ~/.config/rift/auth.json (or under $XDG_CONFIG_HOME), refreshed automatically, and used against the subscription backend at https://chatgpt.com/backend-api/codex. Pick a model your subscription supports with --model or rift config set model <model>. Threads started under one backend are restarted automatically if the stored thread id belongs to the other backend.

Usage

rift "fix the tests"
rift --continue "now add tests"
rift --session <id> "continue this task"
rift --model gpt-5-mini "add authentication"
rift --web-search "update this dependency using current docs"
rift --verbose "explain the failing build and fix it"
rift -i "show compact tool activity while working"
rift --ask "make the requested changes"       # approve writes and shell commands
rift --read-only "review this project"         # no mutations or shell commands

Sessions

Rift stores all chat sessions in one protected embedded SurrealDB database at $XDG_DATA_HOME/rift/sessions.surrealdb (or ~/.local/share/rift/sessions.surrealdb) instead of creating one file per session. Existing sessions.json stores are migrated automatically. Each session records the working directory, model, web search setting, message summary history, and latest OpenAI previous_response_id so it can continue the same Responses API thread. Configuration credentials remain in the separate 0600 config file. The Node.js embedded engine uses SurrealKV storage from @surrealdb/node; no database server is required.

rift sessions list
rift sessions show <id>
rift sessions rm <id>
rift sessions rename <id> <title>
rift sessions export <id> [file]
rift sessions import <file>
rift sessions stats
rift sessions prune <ISO-date> [--cwd]
rift sessions clear --cwd
rift sessions path [id]

Every run resumes the latest session from the current directory. Use rift --new "start a separate task" to explicitly create a fresh session. rift --continue also permits falling back to the latest session from another directory when no local session exists.

Manage stored sessions:

rift sessions flush       # remove all sessions
rift sessions rm <id>     # remove one session

AGENTS.md instructions

Before each new Responses API thread, Rift automatically loads every AGENTS.md between the filesystem root and the session working directory. Files are applied from parent to child, allowing a nested file to refine broader project instructions. The combined instructions are size-limited before being sent to the model.

For example:

AGENTS.md                 # broad defaults
packages/AGENTS.md       # package-wide rules
packages/web/AGENTS.md   # web-package rules

These files are sent to the model as instructions, so do not put secrets in them.

Tools exposed to the model

• read - read a UTF-8 file from the working directory
• write - create or overwrite a UTF-8 file
• edit - replace a unique exact text region in a file
• bash - run shell commands in the working directory
• optional OpenAI web_search_preview when enabled

Unknown command-line options are rejected; use -- when a prompt intentionally contains option-like text. Ctrl-C cancels an in-flight API request. Configuration and session files are written atomically with user-only permissions.