@gitlawb/openclaude 0.1.6 → 0.1.7

package/README.md

@@ -2,282 +2,105 @@
 
 Use Claude Code with **any LLM** — not just Claude.
 
-OpenClaude is a fork of the [Claude Code source leak](https://gitlawb.com/node/repos/z6MkgKkb/instructkr-claude-code) (exposed via npm source maps on March 31, 2026). We added an OpenAI-compatible provider shim so you can plug in GPT-4o, DeepSeek, Gemini, Llama, Mistral, or any model that speaks the OpenAI chat completions API. It now also supports the ChatGPT Codex backend for `codexplan` and `codexspark`.
+OpenClaude is a fork of the [Claude Code source leak](https://gitlawb.com/node/repos/z6MkgKkb/instructkr-claude-code) (exposed via npm source maps on March 31, 2026). We added an OpenAI-compatible provider shim so you can plug in GPT-4o, DeepSeek, Gemini, Llama, Mistral, or any model that speaks the OpenAI chat completions API. It now also supports the ChatGPT Codex backend for `codexplan` and `codexspark`, and local inference via [Atomic Chat](https://atomic.chat/) on Apple Silicon.
 
 All of Claude Code's tools work — bash, file read/write/edit, grep, glob, agents, tasks, MCP — just powered by whatever model you choose.
 
 ---
 
-## Install
+## Start Here
 
-### Option A: npm (recommended)
+If you are new to terminals or just want the easiest path, start with the beginner guides:
 
-```bash
-npm install -g @gitlawb/openclaude
-```
-
-### Option B: From source (requires Bun)
-
-Use Bun `1.3.11` or newer for source builds on Windows. Older Bun versions such as `1.3.4` can fail with a large batch of unresolved module errors during `bun run build`.
-
-```bash
-# Clone from gitlawb
-git clone https://node.gitlawb.com/z6MkqDnb7Siv3Cwj7pGJq4T5EsUisECqR8KpnDLwcaZq5TPr/openclaude.git
-cd openclaude
-
-# Install dependencies
-bun install
-
-# Build
-bun run build
+- [Non-Technical Setup](docs/non-technical-setup.md)
+- [Windows Quick Start](docs/quick-start-windows.md)
+- [macOS / Linux Quick Start](docs/quick-start-mac-linux.md)
 
-# Link globally (optional)
-npm link
-```
-
-### Option C: Run directly with Bun (no build step)
+If you want source builds, Bun workflows, profile launchers, or full provider examples, use:
 
-```bash
-git clone https://node.gitlawb.com/z6MkqDnb7Siv3Cwj7pGJq4T5EsUisECqR8KpnDLwcaZq5TPr/openclaude.git
-cd openclaude
-bun install
-bun run dev
-```
+- [Advanced Setup](docs/advanced-setup.md)
 
 ---
 
-## Quick Start
+## Beginner Install
 
-### 1. Set 3 environment variables
+For most users, install the npm package:
 
 ```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=sk-your-key-here
-export OPENAI_MODEL=gpt-4o
+npm install -g @gitlawb/openclaude
 ```
 
-### 2. Run it
+The package name is `@gitlawb/openclaude`, but the command you run is:
 
 ```bash
-# If installed via npm
 openclaude
-
-# If built from source
-bun run dev
-# or after build:
-node dist/cli.mjs
 ```
 
-That's it. The tool system, streaming, file editing, multi-step reasoning — everything works through the model you picked.
-
-The npm package name is `@gitlawb/openclaude`, but the installed CLI command is still `openclaude`.
+If you install via npm and later see `ripgrep not found`, install ripgrep system-wide and confirm `rg --version` works in the same terminal before starting OpenClaude.
 
 ---
 
-## Provider Examples
+## Fastest Setup
 
-### OpenAI
+### Windows PowerShell
 
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=sk-...
-export OPENAI_MODEL=gpt-4o
-```
-
-### Codex via ChatGPT auth
-
-`codexplan` maps to GPT-5.4 on the Codex backend with high reasoning.
-`codexspark` maps to GPT-5.3 Codex Spark for faster loops.
-
-If you already use the Codex CLI, OpenClaude will read `~/.codex/auth.json`
-automatically. You can also point it elsewhere with `CODEX_AUTH_JSON_PATH` or
-override the token directly with `CODEX_API_KEY`.
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_MODEL=codexplan
+```powershell
+npm install -g @gitlawb/openclaude
 
-# optional if you do not already have ~/.codex/auth.json
-export CODEX_API_KEY=...
+$env:CLAUDE_CODE_USE_OPENAI="1"
+$env:OPENAI_API_KEY="sk-your-key-here"
+$env:OPENAI_MODEL="gpt-4o"
 
 openclaude
 ```
 
-### DeepSeek
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=sk-...
-export OPENAI_BASE_URL=https://api.deepseek.com/v1
-export OPENAI_MODEL=deepseek-chat
-```
-
-### Google Gemini (via OpenRouter)
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=sk-or-...
-export OPENAI_BASE_URL=https://openrouter.ai/api/v1
-export OPENAI_MODEL=google/gemini-2.0-flash
-```
-
-### Ollama (local, free)
-
-```bash
-ollama pull llama3.3:70b
-
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_BASE_URL=http://localhost:11434/v1
-export OPENAI_MODEL=llama3.3:70b
-# no API key needed for local models
-```
-
-### LM Studio (local)
+### macOS / Linux
 
 ```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_BASE_URL=http://localhost:1234/v1
-export OPENAI_MODEL=your-model-name
-```
-
-### Together AI
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=...
-export OPENAI_BASE_URL=https://api.together.xyz/v1
-export OPENAI_MODEL=meta-llama/Llama-3.3-70B-Instruct-Turbo
-```
-
-### Groq
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=gsk_...
-export OPENAI_BASE_URL=https://api.groq.com/openai/v1
-export OPENAI_MODEL=llama-3.3-70b-versatile
-```
-
-### Mistral
-
-```bash
-export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=...
-export OPENAI_BASE_URL=https://api.mistral.ai/v1
-export OPENAI_MODEL=mistral-large-latest
-```
-
-### Azure OpenAI
+npm install -g @gitlawb/openclaude
 
-```bash
 export CLAUDE_CODE_USE_OPENAI=1
-export OPENAI_API_KEY=your-azure-key
-export OPENAI_BASE_URL=https://your-resource.openai.azure.com/openai/deployments/your-deployment/v1
+export OPENAI_API_KEY=sk-your-key-here
 export OPENAI_MODEL=gpt-4o
-```
-
----
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `CLAUDE_CODE_USE_OPENAI` | Yes | Set to `1` to enable the OpenAI provider |
-| `OPENAI_API_KEY` | Yes* | Your API key (*not needed for local models like Ollama) |
-| `OPENAI_MODEL` | Yes | Model name (e.g. `gpt-4o`, `deepseek-chat`, `llama3.3:70b`) |
-| `OPENAI_BASE_URL` | No | API endpoint (defaults to `https://api.openai.com/v1`) |
-| `CODEX_API_KEY` | Codex only | Codex/ChatGPT access token override |
-| `CODEX_AUTH_JSON_PATH` | Codex only | Path to a Codex CLI `auth.json` file |
-| `CODEX_HOME` | Codex only | Alternative Codex home directory (`auth.json` will be read from here) |
-| `OPENCLAUDE_DISABLE_CO_AUTHORED_BY` | No | Set to `1` to suppress the default `Co-Authored-By` trailer in generated git commit messages |
-
-You can also use `ANTHROPIC_MODEL` to override the model name. `OPENAI_MODEL` takes priority.
-
-OpenClaude PR bodies use OpenClaude branding by default. `OPENCLAUDE_DISABLE_CO_AUTHORED_BY` only affects the commit trailer, not PR attribution text.
-
----
-
-## Runtime Hardening
-
-Use these commands to keep the CLI stable and catch environment mistakes early:
-
-```bash
-# quick startup sanity check
-bun run smoke
-
-# validate provider env + reachability
-bun run doctor:runtime
 
-# print machine-readable runtime diagnostics
-bun run doctor:runtime:json
-
-# persist a diagnostics report to reports/doctor-runtime.json
-bun run doctor:report
-
-# full local hardening check (smoke + runtime doctor)
-bun run hardening:check
-
-# strict hardening (includes project-wide typecheck)
-bun run hardening:strict
+openclaude
 ```
 
-Notes:
-- `doctor:runtime` fails fast if `CLAUDE_CODE_USE_OPENAI=1` with a placeholder key (`SUA_CHAVE`) or a missing key for non-local providers.
-- Local providers (for example `http://localhost:11434/v1`) can run without `OPENAI_API_KEY`.
-- Codex profiles validate `CODEX_API_KEY` or the Codex CLI auth file and probe `POST /responses` instead of `GET /models`.
-
-### Provider Launch Profiles
-
-Use profile launchers to avoid repeated environment setup:
+That is enough to start with OpenAI.
 
-```bash
-# one-time profile bootstrap (prefer viable local Ollama, otherwise OpenAI)
-bun run profile:init
+---
 
-# preview the best provider/model for your goal
-bun run profile:recommend -- --goal coding --benchmark
+## Choose Your Guide
 
-# auto-apply the best available local/openai provider/model for your goal
-bun run profile:auto -- --goal latency
+### Beginner
 
-# codex bootstrap (defaults to codexplan and ~/.codex/auth.json)
-bun run profile:codex
+- Want the easiest setup with copy-paste steps: [Non-Technical Setup](docs/non-technical-setup.md)
+- On Windows: [Windows Quick Start](docs/quick-start-windows.md)
+- On macOS or Linux: [macOS / Linux Quick Start](docs/quick-start-mac-linux.md)
 
-# openai bootstrap with explicit key
-bun run profile:init -- --provider openai --api-key sk-...
+### Advanced
 
-# ollama bootstrap with custom model
-bun run profile:init -- --provider ollama --model llama3.1:8b
+- Want source builds, Bun, local profiles, runtime checks, or more provider choices: [Advanced Setup](docs/advanced-setup.md)
 
-# ollama bootstrap with intelligent model auto-selection
-bun run profile:init -- --provider ollama --goal coding
+---
 
-# codex bootstrap with a fast model alias
-bun run profile:init -- --provider codex --model codexspark
+## Common Beginner Choices
 
-# launch using persisted profile (.openclaude-profile.json)
-bun run dev:profile
+### OpenAI
 
-# codex profile (uses CODEX_API_KEY or ~/.codex/auth.json)
-bun run dev:codex
+Best default if you already have an OpenAI API key.
 
-# OpenAI profile (requires OPENAI_API_KEY in your shell)
-bun run dev:openai
+### Ollama
 
-# Ollama profile (defaults: localhost:11434, llama3.1:8b)
-bun run dev:ollama
-```
+Best if you want to run models locally on your own machine.
 
-`profile:recommend` ranks installed Ollama models for `latency`, `balanced`, or `coding`, and `profile:auto` can persist the recommendation directly.
-If no profile exists yet, `dev:profile` now uses the same goal-aware defaults when picking the initial model.
+### Codex
 
-Use `--provider ollama` when you want a local-only path. Auto mode falls back to OpenAI when no viable local chat model is installed.
-Goal-based Ollama selection only recommends among models that are already installed and reachable from Ollama.
+Best if you already use the Codex CLI or ChatGPT Codex backend.
 
-Use `profile:codex` or `--provider codex` when you want the ChatGPT Codex backend.
+### Atomic Chat
 
-`dev:openai`, `dev:ollama`, and `dev:codex` run `doctor:runtime` first and only launch the app if checks pass.
-For `dev:ollama`, make sure Ollama is running locally before launch.
+Best if you want local inference on Apple Silicon with Atomic Chat. See [Advanced Setup](docs/advanced-setup.md).
 
 ---