purrx

A lightweight AI coding agent for your terminal, like Codex CLI but tiny and hackable. Built in plain JavaScript on Node.js (type-checked with JSDoc + tsc), so it runs anywhere Node does with no build step.

Sign in with your ChatGPT account (Plus/Pro/Team) or an OpenAI API key, then let purrx read, write, search, and run code in your project.

╭─────────────────────────────────────────────────╮
│ purrx  your terminal's coding companion           │
│                                                    │
│ model    gpt-5-codex                               │
│ auth     ChatGPT account                           │
│ approval suggest                                   │
│ context  0 mcp · 1 skills · 2 memories             │
╰─────────────────────────────────────────────────╯
  /help for commands · /exit to quit · Ctrl+C to interrupt

❯ add a health check endpoint to the server
⚙ read src/server.js
⚙ edit src/server.js
Added a GET /health endpoint that returns { status: "ok" }.

Features

• Modern TUI. A clean, boxed interface with arrow-key menus, syntax-highlighted Markdown output, and a status header. The visuals stay minimal; the personality is feline.
• Two auth modes. ChatGPT account via OAuth 2.0 + PKCE (reuses the official Codex login flow and auth.json), or a plain OPENAI_API_KEY.
• Streaming responses rendered as styled Markdown with syntax-highlighted code blocks.
• Rich built-in tools. Read, write, surgical edit, list, recursive regex search, glob find, delete, run shell commands, and fetch URLs.
• Web search. The model can use OpenAI's server-side web_search tool for current information.
• MCP support. Connect any Model Context Protocol server over stdio; its tools become available to the agent automatically.
• Project instructions (AGENTS.md). Drop an AGENTS.md in your repo and purrx follows it, merging files from the root down to your working directory.
• Persistent memory. The agent saves durable notes across sessions with the remember tool; they live in memories.d/.
• Skills. Reusable playbooks (SKILL.md) the agent loads on demand with use_skill.
• Command approval. Three policies (suggest, auto-edit, full-auto) with per-tool "always allow" for a session, presented as an arrow-key menu.
• Conversation persistence. Every turn is saved; resume the latest or any past session.
• Accurate model discovery. Lists the models your account can actually use.
• Cross-platform. Windows, macOS, Linux, and Android (Termux), with platform-aware shells, paths, and browser launching.

Requirements

• Node.js 20 or newer (node --version).

Install

From npm (once published):

npm install -g @mewbleh/purrx

Or run from source:

git clone https://github.com/mewbleh/purrx
cd purrx
node bin/purrx.js help

On Termux (Android):

pkg install nodejs
npm install -g @mewbleh/purrx
# optional, for browser login + URL opening:
pkg install termux-api

Quick start

# 1. Sign in (opens your browser for ChatGPT OAuth)
purrx login

#    ...or use an API key instead
purrx login --api-key sk-...
#    ...or just export it
export OPENAI_API_KEY=sk-...

# 2. Start chatting in your project directory
purrx

# 3. Or run a one-off request
purrx exec "explain what this repo does and list the entry points"

Usage

purrx                          Start interactive chat (default)
purrx chat [opts]              Start interactive chat
purrx exec "<request>" [opts]  Run a single request non-interactively
purrx models                   List models your account can use
purrx mcp                      List configured MCP servers
purrx mcp init                 Write an MCP config scaffold
purrx sessions                 List saved sessions
purrx sessions rm <id>         Delete a saved session
purrx login                    Sign in with your ChatGPT account (OAuth)
purrx login --api-key [KEY]    Sign in with an OpenAI API key
purrx logout                   Remove stored credentials
purrx status                   Show platform and sign-in status
purrx help                     Show help

Chat options

| Flag | Description | | --- | --- | | --model <id> | Model to use for this session | | --approval <policy> | suggest, auto-edit, or full-auto (default suggest) | | --continue | Resume the most recent session | | --resume <id> | Resume a specific session |

In-chat commands

| Command | Description | | --- | --- | | /help | Show commands | | /model [id] | Show or pick the model (arrow-key menu) | | /models | List available models | | /approval | Pick the approval policy | | /tools | List available tools (built-in + MCP) | | /skills | List available skills | | /memory | Show stored memories | | /context | Show context-window usage | | /compact | Summarize older history now to free context | | /reset | Clear conversation history | | /session | Show current session info | | /exit | Quit (auto-saves) |

Authentication

purrx reuses the same OAuth client and auth.json format as the official OpenAI Codex CLI, so it interoperates with a Codex login if you set CODEX_HOME.

• ChatGPT account: purrx login runs an OAuth 2.0 Authorization Code flow with PKCE on http://localhost:1455/auth/callback, exchanges the code for tokens, token-exchanges an API key, and stores everything locally. Requests go to the ChatGPT Codex backend tied to your plan.
• API key: stored in auth.json or read from OPENAI_API_KEY. Requests go to api.openai.com.

Tokens refresh automatically when older than ~28 days.

Treat auth.json like a password. It lives in your data directory (see below) with 0600 permissions where supported.

Command approval

purrx asks before doing anything that changes your system, scaled by policy:

• suggest (default): asks before every file write, edit, delete, or shell command. Read-only tools (read, list, search, find, fetch) never prompt.
• auto-edit: auto-approves file writes/edits, still asks before shell commands.
• full-auto: never asks. Used by default for non-interactive purrx exec.

At any prompt you can answer y (yes), n (no), or a (always allow that tool for the session).

MCP (Model Context Protocol)

Connect external tool servers. Create the config scaffold:

purrx mcp init

Then edit config.json in your data directory:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "disabled": false
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    }
  }
}

On the next purrx chat, those servers connect and their tools appear (namespaced mcp__<server>__<tool>). Check with /tools.

Context: AGENTS.md, memory, and skills

purrx gives the model three layers of persistent context.

AGENTS.md (project instructions)

Drop an AGENTS.md file in your project. purrx reads every AGENTS.md from the filesystem root down to your working directory and injects them into the system prompt, with closer files taking precedence. Use it for conventions, build/test commands, and "before you finish" checklists.

# My project
- Use pnpm, not npm.
- Run `pnpm test` before finishing.

Memory (memories.d)

The agent saves durable notes across sessions with the remember tool, for example when you state a preference. They are stored as Markdown in <data-dir>/memories.d/<topic>.md and injected into every future session. View them in-session with /memory, or edit the files directly.

Skills (SKILL.md)

Skills are reusable playbooks the agent loads on demand, keeping the base prompt small. Define one as <name>/SKILL.md either globally in <data-dir>/skills/ or per-project in ./.purrx/skills/:

# Release
description: cut a new versioned release and publish to npm

1. Run the tests.
2. npm version patch
3. git push --follow-tags

purrx shows the name and description: line to the model always; the full body is loaded only when the model calls use_skill. List them with /skills.

Automatic context compaction

Long sessions can approach the model's context window. purrx watches token usage (using the API's reported counts when available, an estimate otherwise) and, once the conversation passes a threshold of the context limit, automatically summarizes the older turns into a single compact summary while keeping recent turns verbatim. This happens transparently before a request is sent, so you can keep working without hitting a wall. Function-call/result pairs are never split.

Check usage anytime with /context, or force a compaction now with /compact. Tune behavior with PURRX_CONTEXT_LIMIT and PURRX_COMPACT_THRESHOLD.

Configuration

| Variable | Purpose | | --- | --- | | OPENAI_API_KEY | Use this key directly (overrides stored auth) | | PURRX_MODEL | Default model (default gpt-5-codex) | | PURRX_CONTEXT_LIMIT | Context window in tokens for compaction (default 256000) | | PURRX_COMPACT_THRESHOLD | Fraction of the limit that triggers compaction (default 0.8) | | PURRX_HOME | Override the data directory | | CODEX_HOME | Share auth.json with the official Codex CLI | | NO_COLOR | Disable colored output | | FORCE_COLOR | Force colored output (e.g. when piping) | | PURRX_DEBUG | Print MCP/server debug logs |

Data directory (credentials, sessions, memories, skills), by platform:

• Windows: %APPDATA%\purrx
• macOS: ~/Library/Application Support/purrx
• Linux / Termux: $XDG_DATA_HOME/purrx or ~/.purrx

Project layout

bin/purrx.js          CLI entry point
scripts/check.js      smoke tests (run in CI)
tsconfig.json         JSDoc type-checking config
src/
  config.js           constants + paths
  platform.js         OS/Termux detection, shells, browser, data dirs
  types.js            shared JSDoc typedefs
  index.js            public programmatic API
  auth/
    pkce.js           PKCE + state generation
    tokens.js         auth.json, JWT, token refresh
    login.js          OAuth login server + API-key login
  api/
    client.js         Responses API streaming
    models.js         model discovery
  tools/
    builtin.js        built-in tools (files, search, shell, memory, skills)
    mcp.js            MCP stdio JSON-RPC client
    registry.js       unifies built-in + MCP + server-side tools
  core/
    agent.js          the tool-calling agent loop
    approval.js       approval policies
    session.js        conversation persistence
    context.js        AGENTS.md, memories, and skills
    compact.js        automatic context-window compaction
  ui/
    theme.js          chalk/boxen/ora styling helpers
    render.js         Markdown to terminal rendering
    tui.js            interactive terminal UI

Development

npm install        # installs runtime + dev dependencies
npm run typecheck  # type-check the JS via JSDoc (tsc --noEmit)
npm run check      # smoke tests
npm test           # both

purrx is written in plain JavaScript with no build step; it runs directly under Node. TypeScript is a dev-only tool that type-checks the JS through JSDoc annotations. Runtime dependencies are kept lean and well maintained:

• chalk - terminal colors
• ora - spinners
• boxen - boxed panels
• @inquirer/prompts - input and menu prompts
• marked + marked-terminal + cli-highlight - Markdown and code rendering

Disclaimer

This is an unofficial, community project and is not affiliated with or endorsed by OpenAI. It uses your local Codex/ChatGPT credentials, which you should treat as password-equivalent. You are responsible for complying with OpenAI's terms of service. Provided as-is, with no warranty.

License

Apache-2.0 © mewbleh