@ruvnet/open-claude-code 2.1.0 → 2.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rUv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,113 +1,383 @@
-# open-claude-code v2 — Technical Guide
+<h1 align="center">Open Claude Code</h1>
+<h3 align="center">Open Source Claude Code CLI — Reverse Engineered & Rebuilt</h3>
 
-## Quick Start
+![Verified release pipeline: detect, validate, test, publish](https://raw.githubusercontent.com/ruvnet/open-claude-code/main/assets/verified-release-flow.svg)
+
+<p align="center">
+  <em>An open source implementation of Anthropic's Claude Code CLI,<br/>
+  built from decompiled source intelligence using <a href="https://github.com/ruvnet/rudevolution">ruDevolution</a>.</em>
+</p>
+
+<p align="center">
+  <img alt="Tests" src="https://img.shields.io/badge/tests-1008_passing-brightgreen?style=flat-square" />
+  <img alt="Tools" src="https://img.shields.io/badge/tools-25-blue?style=flat-square" />
+  <img alt="Commands" src="https://img.shields.io/badge/commands-40-blue?style=flat-square" />
+  <img alt="npm" src="https://img.shields.io/npm/v/@ruvnet/open-claude-code?style=flat-square&label=npm" />
+  <img alt="License" src="https://img.shields.io/badge/License-MIT-blue?style=flat-square" />
+  <img alt="Nightly" src="https://img.shields.io/badge/nightly-verified_releases-brightgreen?style=flat-square" />
+</p>
+
+> **Verified nightly releases:** Detection, source validation, tests, AI analysis and npm publication run automatically. Capability proposals require review before implementation. See the release workflow and ADR-004.
+
+---
+
+## ⚡ Quick Start
+
+```bash
+# Run instantly (no install)
+npx @ruvnet/open-claude-code "explain this codebase"
+
+# Or install globally
+npm install -g @ruvnet/open-claude-code
+occ "hello"
+
+# Interactive mode
+occ
+```
+
+**Requires:** `ANTHROPIC_API_KEY` environment variable set.
 
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...
-node src/index.mjs "hello"          # one-shot
-node src/index.mjs                   # interactive REPL
-node src/index.mjs -m claude-opus-4-6 -p "explain this"  # print mode
-```
-
-## Architecture
-
-```
-v2/src/
-├── core/                    # Core engine
-│   ├── agent-loop.mjs       # Async generator (13 event types, recursive)
-│   ├── streaming.mjs        # SSE handler (all event types)
-│   ├── context-manager.mjs  # Token tracking + compaction
-│   ├── system-prompt.mjs    # CLAUDE.md loading + cache boundary
-│   ├── session.mjs          # Save/resume/teleport
-│   ├── checkpoints.mjs      # File checkpointing + undo
-│   ├── cache.mjs            # Prompt caching
-│   ├── rate-limiter.mjs     # 429/529 handling + backoff
-│   ├── providers.mjs        # 5 AI providers
-│   └── scheduler.mjs        # Cron task scheduling
-├── tools/                   # 25 tools
-│   ├── registry.mjs         # validateInput/call interface
-│   ├── bash.mjs             # Shell (sandboxed, timeout, background)
-│   ├── read.mjs             # File read (PDF, binary detect, line nums)
-│   ├── edit.mjs             # Edit (replace_all, uniqueness check)
-│   ├── write.mjs            # Write (mkdir, overwrite protection)
-│   ├── glob.mjs             # Glob (proper matching, mtime sort)
-│   ├── grep.mjs             # Grep (-i/-n/-A/-B/-C, ripgrep)
-│   ├── agent.mjs            # Subagent (worktree, background, model)
-│   ├── web-fetch.mjs        # URL fetch
-│   ├── web-search.mjs       # Web search
-│   ├── todo-write.mjs       # Task management
-│   ├── notebook-edit.mjs    # Jupyter notebooks
-│   ├── multi-edit.mjs       # Atomic multi-file edits
-│   ├── ls.mjs               # Directory listing
-│   ├── tool-search.mjs      # Deferred tool discovery
-│   ├── ask-user.mjs         # User prompts
-│   ├── skill.mjs            # Skill invocation
-│   ├── send-message.mjs     # Agent team messaging
-│   ├── cron-create.mjs      # Scheduled tasks
-│   ├── cron-delete.mjs
-│   ├── cron-list.mjs
-│   ├── enter-worktree.mjs   # Git worktree
-│   ├── exit-worktree.mjs
-│   ├── remote-trigger.mjs   # Remote execution
-│   ├── lsp.mjs              # Language server
-│   └── read-mcp-resource.mjs
-├── mcp/                     # MCP protocol
-│   ├── client.mjs           # JSON-RPC client
-│   ├── transport-sse.mjs    # SSE transport
-│   ├── transport-shttp.mjs  # Streamable HTTP
-│   └── transport-ws.mjs     # WebSocket
-├── permissions/              # Security
-│   ├── checker.mjs          # 6 modes + interactive prompts
-│   ├── sandbox.mjs          # bubblewrap/seatbelt
-│   ├── injection-check.mjs  # Command injection detection
-│   ├── path-check.mjs       # File path validation
-│   └── prompt.mjs           # Permission prompting
-├── hooks/
-│   └── engine.mjs           # PreToolUse/PostToolUse/Stop/Notification
-├── agents/
-│   ├── loader.mjs           # Agent definition loader
-│   ├── parser.mjs           # JSON/MD frontmatter parser
-│   └── teams.mjs            # Multi-agent teams
-├── skills/
-│   ├── loader.mjs           # Skill discovery
-│   └── runner.mjs           # Skill execution
-├── plugins/
-│   └── loader.mjs           # Plugin discovery + git clone
-├── auth/
-│   └── oauth.mjs            # PKCE OAuth flow
-├── config/
-│   ├── settings.mjs         # 4-source deep merge
-│   ├── cli-args.mjs         # All CLI flags
-│   └── env.mjs              # 104 env vars
-├── ui/
-│   ├── repl.mjs             # Interactive REPL
-│   ├── ink-app.mjs          # Rich terminal output
-│   └── commands.mjs         # 40 slash commands
-├── telemetry/
-│   └── index.mjs            # Telemetry stub
-└── index.mjs                # Entry point
-
-test/
-└── test.mjs                 # 1,581 tests
-```
-
-## Stats
-
-| Metric | Value |
-|--------|:-----:|
-| Source files | 61 |
-| Lines of code | 8,314 |
-| Tests | 1,581 (0 failures) |
-| Tools | 25 |
-| Slash commands | 40 |
-| MCP transports | 4 |
-| AI providers | 5 |
-| Env vars | 104 |
-| Permission modes | 6 |
-
-## Tests
+npx @ruvnet/open-claude-code "what files are in this directory?"
+```
+
+---
+
+## 🧠 What Is This?
+
+**Open Claude Code** is a ground-up open source rebuild of Anthropic's [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code), informed by [ruDevolution's](https://github.com/ruvnet/rudevolution) AI-powered decompilation of the published npm package.
+
+It's not a copy — it's a clean-room implementation that mirrors the actual Claude Code architecture: async generator agent loop, 25 tools, 4 MCP transports, 6 permission modes, hooks, settings chain, sessions, and more.
+
+**1,008 unit tests plus installed-package behavioral checks. Full upstream parity is not established.**
+
+---
+
+## 📦 Installation
+
+### npx (no install needed)
+
+```bash
+npx @ruvnet/open-claude-code "your prompt here"
+```
+
+### Global install
 
 ```bash
-node test/test.mjs
-# Tests: 1581 total, 1581 passed, 0 failed
+npm install -g @ruvnet/open-claude-code
+occ "your prompt here"
 ```
+
+### From source
+
+```bash
+git clone https://github.com/ruvnet/open-claude-code.git
+cd open-claude-code/v2
+export ANTHROPIC_API_KEY=sk-ant-...
+node src/index.mjs "hello"
+```
+
+---
+
+## 🖥️ Usage
+
+### One-shot mode
+
+```bash
+occ "explain the auth module"
+occ "fix the bug in server.js"
+occ "create a REST API for user management"
+occ "find all TODO comments in this project"
+```
+
+### Interactive REPL
+
+```bash
+occ
+# > explain this codebase
+# > /help
+# > /tools
+# > /model claude-opus-4-6
+# > refactor the database layer
+# > /cost
+# > /exit
+```
+
+### CLI Options
+
+```bash
+occ [options] [prompt]
+
+Options:
+  -m, --model <model>          Model to use (default: claude-sonnet-4-6)
+  -p, --print                  Print mode (non-interactive, output only)
+  --permission-mode <mode>     Permission mode: default, auto, plan, acceptEdits,
+                               bypassPermissions, dontAsk
+  --system-prompt <text>       Override system prompt
+  --add-dir <path>             Additional CLAUDE.md directory
+  --max-turns <n>              Maximum conversation turns
+  --allowedTools <tools>       Comma-separated allowed tools
+  --disallowedTools <tools>    Comma-separated denied tools
+  --output-format <fmt>        Output: text, json, stream-json
+  -v, --verbose                Verbose output
+  -d, --debug                  Debug mode
+  --version                    Show version
+  -h, --help                   Show help
+```
+
+### Examples
+
+```bash
+# Use a different model
+occ -m claude-opus-4-6 "design a database schema for a blog"
+
+# Print mode (for piping)
+occ -p "list all functions in src/" > functions.txt
+
+# Plan mode (read-only, no edits)
+occ --permission-mode plan "review the security of auth.js"
+
+# Restrict tools
+occ --allowedTools "Read,Glob,Grep" "find all API endpoints"
+
+# With custom system prompt
+occ --system-prompt "You are a senior Go developer" "review main.go"
+```
+
+---
+
+## 🔧 Interactive Commands
+
+40 slash commands available in REPL mode:
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show all commands |
+| `/model <name>` | Switch model mid-conversation |
+| `/tools` | List available tools |
+| `/tokens` | Show current token usage |
+| `/cost` | Show session cost estimate |
+| `/compact` | Compact context window |
+| `/undo` | Undo last file edit |
+| `/clear` | Clear conversation history |
+| `/doctor` | Check API connectivity + health |
+| `/fast` | Toggle fast mode (Haiku) |
+| `/effort <level>` | Set effort: low, medium, high, max |
+| `/resume [id]` | Resume a previous session |
+| `/sessions` | List saved sessions |
+| `/agents` | List custom agents |
+| `/skills` | List available skills |
+| `/hooks` | Show active hooks |
+| `/config` | Show current settings |
+| `/permissions` | Show permission mode |
+| `/mcp` | Show MCP server status |
+| `/memory` | Show memory usage |
+| `/exit` | Exit |
+
+---
+
+## 🔨 Tools
+
+25 built-in tools matching Claude Code's tool system:
+
+| Tool | Description |
+|------|-------------|
+| **Bash** | Execute shell commands (sandboxed) |
+| **Read** | Read files with line numbers |
+| **Edit** | Replace strings in files |
+| **Write** | Create/overwrite files |
+| **Glob** | Find files by pattern |
+| **Grep** | Search file contents (regex) |
+| **LS** | List directory contents |
+| **Agent** | Spawn sub-agents |
+| **WebFetch** | Fetch URL content |
+| **WebSearch** | Web search |
+| **TodoWrite** | Task management |
+| **NotebookEdit** | Edit Jupyter notebooks |
+| **MultiEdit** | Atomic multi-file edits |
+| **ToolSearch** | Discover deferred tools |
+| **AskUser** | Prompt user for input |
+| **Skill** | Invoke a skill |
+| **SendMessage** | Agent team messaging |
+| **CronCreate/Delete/List** | Scheduled tasks |
+| **EnterWorktree/ExitWorktree** | Git worktree isolation |
+| **RemoteTrigger** | Remote execution |
+| **LSP** | Language server protocol |
+| **ReadMcpResource** | Read MCP resources |
+
+---
+
+## ⚙️ Configuration
+
+### Settings
+
+Create `.claude/settings.json` in your project or `~/.claude/settings.json` globally:
+
+```json
+{
+  "model": "claude-sonnet-4-6",
+  "permissions": {
+    "defaultMode": "auto"
+  },
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{ "type": "command", "command": "echo 'Running bash...'" }]
+    }]
+  },
+  "autoCompactEnabled": true,
+  "alwaysThinkingEnabled": true
+}
+```
+
+Settings are loaded from 4 sources (in priority order):
+1. `.claude/settings.local.json` (local, gitignored)
+2. `.claude/settings.json` (project, shared)
+3. `~/.claude/settings.json` (user global)
+4. Managed policy (enterprise)
+
+### CLAUDE.md
+
+Create a `CLAUDE.md` in your project root to customize behavior:
+
+```markdown
+# Project Rules
+- Always use TypeScript
+- Follow TDD
+- Keep files under 500 lines
+```
+
+CLAUDE.md files are loaded from: `~/.claude/CLAUDE.md` → parent directories → project root → `.claude/CLAUDE.md`.
+
+### Custom Agents
+
+Create `.claude/agents/reviewer.md`:
+
+```markdown
+---
+name: reviewer
+description: Code review specialist
+model: claude-sonnet-4-6
+tools: [Read, Glob, Grep]
+---
+
+You are a thorough code reviewer. Check for bugs, security issues, and style.
+```
+
+### Skills
+
+Create `.claude/skills/deploy/SKILL.md`:
+
+```markdown
+---
+name: deploy
+description: Deploy to production
+---
+
+1. Run tests: npm test
+2. Build: npm run build
+3. Deploy: ./scripts/deploy.sh
+```
+
+Invoke with `/deploy` in the REPL.
+
+---
+
+## 🔐 Multi-Provider Support
+
+Adapters exist for Anthropic, OpenAI-compatible endpoints and Google. Installed-package E2E covers Anthropic and OpenAI-compatible tool roundtrips; Google is not covered by that gate. Bedrock and Vertex remain stubs.
+
+```bash
+# Anthropic (default)
+ANTHROPIC_API_KEY=... occ "hello"
+
+# OpenAI
+OPENAI_API_KEY=... occ -m gpt-4o "hello"
+
+# Google
+GOOGLE_API_KEY=... occ -m gemini-2.5-flash "hello"
+
+
+```
+
+---
+
+## 🔗 MCP Integration
+
+Connect to MCP servers for additional tools:
+
+```json
+// .mcp.json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "my-mcp-server"],
+      "env": { "API_KEY": "..." }
+    }
+  }
+}
+```
+
+Supports 4 transports: stdio, SSE, Streamable HTTP, WebSocket.
+
+---
+
+## 🔍 Background: The Claude Code Source Leak
+
+On March 31, 2026, Anthropic accidentally shipped source maps in the Claude Code npm package, [exposing the full TypeScript source](https://www.sabrina.dev/p/claude-code-source-leak-analysis). This project takes a different approach — we use [ruDevolution](https://github.com/ruvnet/rudevolution) to analyze the **published npm package** legally and rebuild from that intelligence.
+
+### What ruDevolution Found
+
+| Discovery | Evidence |
+|-----------|---------|
+| 🤖 Agent Teams | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` |
+| 🌙 Auto Dream Mode | `tengu_auto_dream_completed` |
+| 🔮 claude-opus-4-6 | Unreleased model ID |
+| 🔐 6 "amber" codenames | Internal feature gates |
+| ☁️ Cloud Code Runner | BYOC compute |
+| 📡 MCP Streamable HTTP | New transport |
+
+[Download decompiled releases →](https://github.com/ruvnet/rudevolution/releases)
+
+---
+
+## ⚖️ Legal
+
+This is a **clean-room implementation** — no leaked source used. Architecture informed by analysis of the published npm package, legal under US DMCA §1201(f), EU Software Directive Art. 6, UK CDPA §50B.
+
+---
+
+## 📚 Related
+
+- [ruDevolution](https://github.com/ruvnet/rudevolution) — AI-Powered JavaScript Decompiler
+- [Decompiled Releases](https://github.com/ruvnet/rudevolution/releases) — Every Claude Code version
+- [v2 Architecture (ADR-001)](./docs/adr/ADR-001-v2-architecture.md)
+- [Path to 100% (ADR-002)](./docs/adr/ADR-002-path-to-100-percent.md)
+
+## Verified release automation
+
+![Installed CLI end to end verification](https://raw.githubusercontent.com/ruvnet/open-claude-code/main/assets/cli-e2e.svg)
+
+Runs daily at 03:00 UTC. Unchanged upstream versions are explicitly reported as no-op runs.
+
+Publication requires unit and regression tests, a dependency audit, validated source recovery, successful AI analysis, clean package installation tests, and a live provider Read tool roundtrip against a fresh random fixture. The exact tested tarball is published to npm, its SHA-512 integrity verified, and the registry version installed and exercised again.
+
+Only then does the upstream checkpoint advance. Failed gates stop publication and create an investigation issue. GitHub releases attach the package, source commit receipt and analysis. Nightly versions use the npm nightly tag. Stable releases require the manually selected latest channel.
+
+Required repository secrets: AI_API_KEY (OpenRouter) and NPM_TOKEN with publishing permission. GITHUB_TOKEN is supplied by GitHub Actions. ruOS bindings provision credentials without printing their values.
+
+```bash
+gh workflow run nightly.yml -f force_release=true -f channel=nightly
+npm install @ruvnet/open-claude-code@nightly
+```
+
+Structural changes produce review proposals, not implemented features. Concrete behavioral specifications and new tests are required before implementing them. Full upstream parity is not established.
+
+See [release integrity ADR](docs/adr/ADR-004-verified-npm-publication.md).
+
+
+## 📄 License
+
+MIT

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@ruvnet/open-claude-code",
-  "version": "2.1.0",
-  "description": "Open source Claude Code CLI — based on ruDevolution decompilation of v2.1.91",
+  "version": "2.1.1",
+  "description": "Open source agentic coding CLI with verified nightly upstream analysis",
   "type": "module",
   "bin": {
     "occ": "src/index.mjs"
   },
   "files": [
     "src/",
-    "test/"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "start": "node src/index.mjs",
@@ -31,7 +32,7 @@
     "url": "https://github.com/ruvnet/open-claude-code/issues"
   },
   "homepage": "https://github.com/ruvnet/open-claude-code#readme",
-  "main": "index.js",
+  "main": "src/index.mjs",
   "directories": {
     "test": "test"
   },
@@ -41,5 +42,11 @@
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "react": "^18.3.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/auth/oauth.mjs

@@ -6,6 +6,7 @@
  * - Authorization code + PKCE
  * - Token refresh
  * - Credential storage in ~/.claude/credentials
+ * - Codex (OpenAI) OAuth via CODEX_CLIENT_ID / OPENAI_CLIENT_ID env vars
  */
 
 import crypto from 'crypto';
@@ -13,24 +14,63 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 
+/**
+ * Well-known provider presets.
+ * Consumers can pass `provider: 'codex'` (or `'openai'`) to switch endpoints.
+ */
+const PROVIDER_PRESETS = {
+    anthropic: {
+        authUrl: 'https://console.anthropic.com/oauth/authorize',
+        tokenUrl: 'https://console.anthropic.com/oauth/token',
+        deviceUrl: 'https://console.anthropic.com/oauth/device',
+    },
+    codex: {
+        authUrl: 'https://auth.openai.com/authorize',
+        tokenUrl: 'https://auth.openai.com/oauth/token',
+        deviceUrl: 'https://auth.openai.com/oauth/device/code',
+    },
+    openai: {
+        authUrl: 'https://auth.openai.com/authorize',
+        tokenUrl: 'https://auth.openai.com/oauth/token',
+        deviceUrl: 'https://auth.openai.com/oauth/device/code',
+    },
+};
+
 export class OAuthClient {
     /**
      * @param {string} clientId - OAuth client ID
      * @param {object} [options]
-     * @param {string} [options.authUrl] - authorization endpoint
-     * @param {string} [options.tokenUrl] - token endpoint
-     * @param {string} [options.deviceUrl] - device authorization endpoint
+     * @param {string} [options.provider] - 'anthropic' | 'codex' | 'openai' (default: 'anthropic')
+     * @param {string} [options.authUrl] - authorization endpoint (overrides provider preset)
+     * @param {string} [options.tokenUrl] - token endpoint (overrides provider preset)
+     * @param {string} [options.deviceUrl] - device authorization endpoint (overrides provider preset)
      * @param {string} [options.credentialsPath] - path to store credentials
      */
     constructor(clientId, options = {}) {
         this.clientId = clientId;
-        this.authUrl = options.authUrl || 'https://console.anthropic.com/oauth/authorize';
-        this.tokenUrl = options.tokenUrl || 'https://console.anthropic.com/oauth/token';
-        this.deviceUrl = options.deviceUrl || 'https://console.anthropic.com/oauth/device';
+
+        const preset = PROVIDER_PRESETS[options.provider] || PROVIDER_PRESETS.anthropic;
+        this.authUrl = options.authUrl || preset.authUrl;
+        this.tokenUrl = options.tokenUrl || preset.tokenUrl;
+        this.deviceUrl = options.deviceUrl || preset.deviceUrl;
         this.credentialsPath = options.credentialsPath ||
             path.join(os.homedir(), '.claude', 'credentials');
     }
 
+    /**
+     * Create a client pre-configured for Codex / OpenAI auth.
+     * Falls back to CODEX_CLIENT_ID → OPENAI_CLIENT_ID env vars.
+     * @param {object} [options]
+     * @returns {OAuthClient}
+     */
+    static forCodex(options = {}) {
+        const clientId = options.clientId ||
+            process.env.CODEX_CLIENT_ID ||
+            process.env.OPENAI_CLIENT_ID ||
+            'codex-default';
+        return new OAuthClient(clientId, { ...options, provider: 'codex' });
+    }
+
     /**
      * Generate a PKCE code verifier and challenge.
      * @returns {{ verifier: string, challenge: string }}

package/src/config/cli-args.mjs

@@ -32,6 +32,8 @@ export function parseArgs(args) {
         debug: false,
         showVersion: false,
         showHelp: false,
+        // Opt-in metaharness self-optimization. null = unset (defer to env/setting).
+        selfOptimize: null,
     };
 
     for (let i = 0; i < args.length; i++) {
@@ -86,6 +88,14 @@ export function parseArgs(args) {
                 result.debug = true;
                 break;
 
+            case '--self-optimize':
+                result.selfOptimize = true;
+                break;
+
+            case '--no-self-optimize':
+                result.selfOptimize = false;
+                break;
+
             case '--version':
                 result.showVersion = true;
                 break;
@@ -127,13 +137,23 @@ Options:
   --disallowedTools <tools>  Comma-separated list of denied tools
   --verbose, -v              Verbose output
   --debug, -d                Debug mode
+  --self-optimize            Route model calls through the metaharness cost-cascade
+                             (cheap base -> escalate) and record real outcomes (opt-in)
+  --no-self-optimize         Force self-optimization off (overrides env/setting)
   --version                  Show version
   --help, -h                 Show this help
 
+Subcommands:
+  occ optimize <status|route|report|reset|help>   Inspect/manage the self-optimization router (no model calls)
+  occ redblue [...]          Delegate to @metaharness/redblue CLI (self red/blue-team testing, via npx)
+  occ darwin  [...]          Delegate to @metaharness/darwin CLI (config evolution, via npx)
+
 Examples:
   occ                        Start interactive REPL
   occ -p "What is 2+2?"     Run prompt and exit
   occ -m claude-haiku-4-5    Use Haiku model
   occ --debug -p "Fix bug"  Debug mode with prompt
+  occ --self-optimize -p "..."   Run with the cost-cascade router enabled
+  occ optimize status        Show the router config and recorded outcomes
 `.trim();
 }

package/src/config/env.mjs

@@ -30,6 +30,8 @@ export const ENV_SCHEMA = {
     CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: { type: 'boolean', default: false, description: 'Enable agent teams' },
     CLAUDE_CODE_DEBUG: { type: 'boolean', default: false, description: 'Debug mode' },
     CLAUDE_CODE_DISABLE_TELEMETRY: { type: 'boolean', default: false, description: 'Disable telemetry' },
+    CLAUDE_CODE_SELF_OPTIMIZE: { type: 'boolean', default: false, description: 'Enable metaharness cost-cascade self-optimization (opt-in)' },
+    CLAUDE_CODE_OPTIMIZE_DIR: { type: 'string', description: 'Directory for self-optimization outcome store' },
 
     // Permission and Security
     CLAUDE_CODE_PERMISSION_MODE: { type: 'string', default: 'default', description: 'Permission mode' },