@mewbleh/purrx 1.0.8

package/AGENTS.md

@@ -0,0 +1,31 @@
+# purrx project instructions
+
+These instructions are loaded automatically by purrx (and other AGENTS.md-aware
+agents) when working in this repository.
+
+## Conventions
+
+- Language: plain JavaScript (ES modules), type-checked with JSDoc + `tsc`.
+- No build step. The code must run directly with `node bin/purrx.js`.
+- Keep runtime dependencies lean and well maintained.
+- Match the existing style: 2-space indent, double quotes, trailing commas.
+
+## Before you finish
+
+- Run `npm run typecheck` and `npm run check`; both must pass.
+- Do not commit credentials, `auth.json`, or anything under the data directory.
+
+## Layout
+
+- CLI entry: `bin/purrx.js`
+- Source by domain: `src/auth`, `src/api`, `src/tools`, `src/core`, `src/ui`
+- Tests/smoke checks: `scripts/check.js`
+
+## Context systems
+
+- `AGENTS.md` files are read from the filesystem root down to the working
+  directory; closer files take precedence.
+- Persistent memories live in `<data-dir>/memories.d/*.md` and are injected into
+  every session. The agent writes them via the `remember` tool.
+- Skills are reusable playbooks in `<data-dir>/skills/<name>/SKILL.md` or
+  `./.purrx/skills/<name>/SKILL.md`. The agent loads one with `use_skill`.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 mewbleh
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,314 @@
+# 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](https://modelcontextprotocol.io) 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):
+
+```bash
+npm install -g @mewbleh/purrx
+```
+
+Or run from source:
+
+```bash
+git clone https://github.com/mewbleh/purrx
+cd purrx
+node bin/purrx.js help
+```
+
+On **Termux** (Android):
+
+```bash
+pkg install nodejs
+npm install -g @mewbleh/purrx
+# optional, for browser login + URL opening:
+pkg install termux-api
+```
+
+## Quick start
+
+```bash
+# 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:
+
+```bash
+purrx mcp init
+```
+
+Then edit `config.json` in your data directory:
+
+```json
+{
+  "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.
+
+```markdown
+# 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/`:
+
+```markdown
+# 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
+
+```bash
+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`](https://github.com/chalk/chalk) - terminal colors
+- [`ora`](https://github.com/sindresorhus/ora) - spinners
+- [`boxen`](https://github.com/sindresorhus/boxen) - boxed panels
+- [`@inquirer/prompts`](https://github.com/SBoudrias/Inquirer.js) - input and menu prompts
+- [`marked`](https://github.com/markedjs/marked) + [`marked-terminal`](https://github.com/mikaelbr/marked-terminal) + [`cli-highlight`](https://github.com/felixfbecker/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