@ruvnet/open-claude-code 2.0.1 → 2.1.0

package/README.md

@@ -0,0 +1,113 @@
+# open-claude-code v2 — Technical Guide
+
+## Quick Start
+
+```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
+
+```bash
+node test/test.mjs
+# Tests: 1581 total, 1581 passed, 0 failed
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruvnet/open-claude-code",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Open source Claude Code CLI — based on ruDevolution decompilation of v2.1.91",
   "type": "module",
   "bin": {
@@ -23,5 +23,23 @@
     "open-source"
   ],
   "license": "MIT",
-  "repository": "https://github.com/ruvnet/open-claude-code"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ruvnet/open-claude-code.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ruvnet/open-claude-code/issues"
+  },
+  "homepage": "https://github.com/ruvnet/open-claude-code#readme",
+  "main": "index.js",
+  "directories": {
+    "test": "test"
+  },
+  "author": "",
+  "dependencies": {
+    "ink": "^5.2.1",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^18.3.1"
+  }
 }

package/src/config/env.mjs

@@ -79,8 +79,6 @@ export const ENV_SCHEMA = {
     ANTHROPIC_AUTH_TOKEN: { type: 'string', description: 'Anthropic auth token (OAuth)' },
 
     // Extended: Sandbox & Security
-    CLAUDE_CODE_FORCE_SANDBOX: { type: 'boolean', default: false, description: 'Force sandbox for all commands' },
-    CLAUDE_CODE_BUBBLEWRAP: { type: 'boolean', default: false, description: 'Enable bubblewrap sandbox on Linux' },
     CLAUDE_CODE_SANDBOX_PLATFORM: { type: 'string', description: 'Override sandbox platform (linux/darwin)' },
     CLAUDE_CODE_INJECTION_CHECK: { type: 'boolean', default: true, description: 'Enable command injection checks' },
     CLAUDE_CODE_PATH_CHECK: { type: 'boolean', default: true, description: 'Enable file path validation' },

package/src/config/settings.mjs

@@ -3,7 +3,6 @@
  *
  * Supports all 76 properties from Claude Code's settings schema.
  * Five-layer hierarchy: user > project > local > managed > feature flags.
- * Deep merge with source tracking and write-back.
  */
 import fs from 'fs';
 import path from 'path';
@@ -61,101 +60,28 @@ export const SETTINGS_SCHEMA = {
     featureFlags: {},
 };
 
-/** Sources in load order (first = lowest priority, last = highest) */
-const SCOPE_NAMES = ['managed', 'user', 'project', 'local'];
-
-/**
- * Get file paths for each settings scope.
- * @param {string} [cwd]
- * @returns {Record<string, string>}
- */
-export function getSettingsPaths(cwd = process.cwd()) {
-    return {
-        user: path.join(os.homedir(), '.claude', 'settings.json'),
-        project: path.join(cwd, '.claude', 'settings.json'),
-        local: path.join(cwd, '.claude', 'settings.local.json'),
-        managed: path.join(os.homedir(), '.claude', 'settings.managed.json'),
-    };
-}
-
-/**
- * Load settings with 4-source deep merge and source tracking.
- * Order: defaults -> managed -> user -> project -> local -> env overrides
- * @param {string} [cwd]
- * @returns {Promise<object>} merged settings with _sources metadata
- */
-export async function loadSettings(cwd) {
-    const paths = getSettingsPaths(cwd);
+export async function loadSettings() {
     const chain = [
-        { scope: 'managed', file: paths.managed },
-        { scope: 'user', file: paths.user },
-        { scope: 'project', file: paths.project },
-        { scope: 'local', file: paths.local },
+        path.join(os.homedir(), '.claude', 'settings.json'),
+        path.join(process.cwd(), '.claude', 'settings.json'),
+        path.join(process.cwd(), '.claude', 'settings.local.json'),
     ];
 
     let merged = deepClone(SETTINGS_SCHEMA);
-    const sources = {};
 
-    // Track defaults
-    trackSources(sources, SETTINGS_SCHEMA, 'default', '');
-
-    for (const { scope, file } of chain) {
+    for (const file of chain) {
         try {
             const data = JSON.parse(fs.readFileSync(file, 'utf-8'));
             merged = deepMerge(merged, data);
-            trackSources(sources, data, scope, '');
         } catch {
-            // File not found or invalid — skip
+            // File not found or invalid
         }
     }
 
-    applyEnvOverrides(merged, sources);
-
-    // Attach metadata (non-enumerable so it does not interfere with tests)
-    Object.defineProperty(merged, '_sources', { value: sources, enumerable: false, writable: true });
-    Object.defineProperty(merged, '_paths', { value: paths, enumerable: false, writable: true });
-
+    applyEnvOverrides(merged);
     return merged;
 }
 
-/**
- * Save a single setting back to the correct scope file.
- * @param {'user'|'project'|'local'} scope
- * @param {string} key — dot-separated path (e.g. "permissions.defaultMode")
- * @param {*} value
- * @param {string} [cwd]
- */
-export function saveSettings(scope, key, value, cwd) {
-    const paths = getSettingsPaths(cwd);
-    const file = paths[scope];
-    if (!file) throw new Error(`Unknown scope: ${scope}`);
-
-    let existing = {};
-    try {
-        existing = JSON.parse(fs.readFileSync(file, 'utf-8'));
-    } catch {
-        // New file
-    }
-
-    setNestedValue(existing, key, value);
-
-    const dir = path.dirname(file);
-    fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(existing, null, 2) + '\n');
-}
-
-/**
- * Get the source scope for a specific setting key.
- * @param {object} settings — settings object returned by loadSettings
- * @param {string} key — dot-separated path
- * @returns {string} scope name ('default', 'user', 'project', 'local', 'managed', 'env')
- */
-export function getSettingSource(settings, key) {
-    return settings._sources?.[key] || 'default';
-}
-
-// ---------- Helpers ----------
-
 function deepClone(obj) {
     return JSON.parse(JSON.stringify(obj));
 }
@@ -163,8 +89,7 @@ function deepClone(obj) {
 function deepMerge(target, source) {
     const result = { ...target };
     for (const [key, value] of Object.entries(source)) {
-        if (value && typeof value === 'object' && !Array.isArray(value)
-            && typeof result[key] === 'object' && !Array.isArray(result[key])) {
+        if (value && typeof value === 'object' && !Array.isArray(value) && typeof result[key] === 'object' && !Array.isArray(result[key])) {
             result[key] = deepMerge(result[key] || {}, value);
         } else {
             result[key] = value;
@@ -173,53 +98,22 @@ function deepMerge(target, source) {
     return result;
 }
 
-function trackSources(sources, obj, scope, prefix) {
-    for (const [key, value] of Object.entries(obj)) {
-        const fullKey = prefix ? `${prefix}.${key}` : key;
-        sources[fullKey] = scope;
-        if (value && typeof value === 'object' && !Array.isArray(value)) {
-            trackSources(sources, value, scope, fullKey);
-        }
-    }
-}
-
-function setNestedValue(obj, key, value) {
-    const parts = key.split('.');
-    let cur = obj;
-    for (let i = 0; i < parts.length - 1; i++) {
-        if (!cur[parts[i]] || typeof cur[parts[i]] !== 'object') {
-            cur[parts[i]] = {};
-        }
-        cur = cur[parts[i]];
+function applyEnvOverrides(settings) {
+    if (process.env.ANTHROPIC_MODEL) settings.model = process.env.ANTHROPIC_MODEL;
+    if (process.env.CLAUDE_CODE_SUBAGENT_MODEL) settings.subagentModel = process.env.CLAUDE_CODE_SUBAGENT_MODEL;
+    if (process.env.CLAUDE_CODE_MAX_OUTPUT_TOKENS) {
+        const n = parseInt(process.env.CLAUDE_CODE_MAX_OUTPUT_TOKENS, 10);
+        if (!isNaN(n)) { settings.maxOutputTokens = n; settings.maxTokens = n; }
     }
-    cur[parts[parts.length - 1]] = value;
-}
-
-function applyEnvOverrides(settings, sources) {
-    const envMap = [
-        ['ANTHROPIC_MODEL', (v) => { settings.model = v; }, 'model'],
-        ['CLAUDE_CODE_SUBAGENT_MODEL', (v) => { settings.subagentModel = v; }, 'subagentModel'],
-        ['CLAUDE_CODE_MAX_OUTPUT_TOKENS', (v) => {
-            const n = parseInt(v, 10);
-            if (!isNaN(n)) { settings.maxOutputTokens = n; settings.maxTokens = n; }
-        }, 'maxOutputTokens'],
-        ['CLAUDE_CODE_MAX_CONTEXT_TOKENS', (v) => {
-            const n = parseInt(v, 10);
-            if (!isNaN(n)) settings.maxContextTokens = n;
-        }, 'maxContextTokens'],
-        ['CLAUDE_CODE_BRIEF', (v) => { if (v === '1') settings.briefMode = true; }, 'briefMode'],
-        ['CLAUDE_CODE_DEBUG', (v) => { if (v === '1') settings.debugMode = true; }, 'debugMode'],
-        ['CLAUDE_CODE_PERMISSION_MODE', (v) => { settings.permissions.defaultMode = v; }, 'permissions.defaultMode'],
-        ['CLAUDE_CODE_STREAMING', (v) => { if (v === '0') settings.stream = false; }, 'stream'],
-        ['CLAUDE_CODE_THINKING', (v) => { if (v === '1') settings.alwaysThinkingEnabled = true; }, 'alwaysThinkingEnabled'],
-        ['CLAUDE_CODE_DISABLE_CRON', (v) => { if (v === '1') settings.cronEnabled = false; }, 'cronEnabled'],
-        ['CLAUDE_CODE_ENABLE_TASKS', (v) => { if (v === '1') settings.enableTeams = true; }, 'enableTeams'],
-    ];
-
-    for (const [envKey, apply, settingsKey] of envMap) {
-        if (process.env[envKey]) {
-            apply(process.env[envKey]);
-            if (sources) sources[settingsKey] = 'env';
-        }
+    if (process.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS) {
+        const n = parseInt(process.env.CLAUDE_CODE_MAX_CONTEXT_TOKENS, 10);
+        if (!isNaN(n)) settings.maxContextTokens = n;
     }
+    if (process.env.CLAUDE_CODE_BRIEF === '1') settings.briefMode = true;
+    if (process.env.CLAUDE_CODE_DEBUG === '1') settings.debugMode = true;
+    if (process.env.CLAUDE_CODE_PERMISSION_MODE) settings.permissions.defaultMode = process.env.CLAUDE_CODE_PERMISSION_MODE;
+    if (process.env.CLAUDE_CODE_STREAMING === '0') settings.stream = false;
+    if (process.env.CLAUDE_CODE_THINKING === '1') settings.alwaysThinkingEnabled = true;
+    if (process.env.CLAUDE_CODE_DISABLE_CRON === '1') settings.cronEnabled = false;
+    if (process.env.CLAUDE_CODE_ENABLE_TASKS === '1') settings.enableTeams = true;
 }

package/src/core/session.mjs

@@ -1,9 +1,8 @@
 /**
- * Session Manager — save, resume, list, and teleport sessions.
+ * Session Manager — save, resume, and teleport sessions.
  *
  * Sessions are stored at ~/.claude/projects/<hash>/session.json
  * and contain conversation history, token usage, and metadata.
- * Supports listing recent sessions and resuming by ID.
  */
 
 import fs from 'fs';
@@ -32,16 +31,8 @@ export class SessionManager {
     }
 
     /**
-     * Get the base projects directory (for listing all sessions).
-     */
-    static getProjectsDir() {
-        return path.join(os.homedir(), '.claude', 'projects');
-    }
-
-    /**
-     * Save the current session state (messages + full state).
+     * Save the current session state.
      * @param {object} state - agent loop state to save
-     * @returns {string} path to saved session file
      */
     save(state) {
         const dir = this.getSessionDir();
@@ -60,101 +51,28 @@ export class SessionManager {
             systemPrompt: state.systemPrompt,
         };
 
-        // Save current session
         const filePath = path.join(dir, 'session.json');
         fs.writeFileSync(filePath, JSON.stringify(session, null, 2));
-
-        // Also save to sessions history for listing
-        this._saveToHistory(dir, session);
-
         return filePath;
     }
 
     /**
-     * Save a minimal entry to sessions history for listing.
-     */
-    _saveToHistory(dir, session) {
-        const historyFile = path.join(dir, 'sessions-history.json');
-        let history = [];
-        try {
-            history = JSON.parse(fs.readFileSync(historyFile, 'utf-8'));
-        } catch { /* new file */ }
-
-        // Remove old entry with same ID
-        history = history.filter(h => h.id !== session.id);
-
-        history.push({
-            id: session.id,
-            projectDir: session.projectDir,
-            startedAt: session.startedAt,
-            savedAt: session.savedAt,
-            model: session.model,
-            turnCount: session.turnCount,
-            tokenUsage: session.tokenUsage,
-            messageCount: (session.messages || []).length,
-        });
-
-        // Keep last 50
-        if (history.length > 50) history = history.slice(-50);
-        fs.writeFileSync(historyFile, JSON.stringify(history, null, 2));
-    }
-
-    /**
-     * Load and restore a saved session into agent loop state.
-     * Fully restores messages so conversation can continue.
+     * Resume a saved session.
      * @param {object} state - agent loop state to restore into
-     * @param {string} [sessionId] - optional specific session ID to load
      * @returns {boolean} true if session was restored
      */
-    resume(state, sessionId) {
+    resume(state) {
         const dir = this.getSessionDir();
-
-        if (sessionId) {
-            // Look up specific session from history
-            return this._resumeById(state, dir, sessionId);
-        }
-
-        // Load most recent session
         const filePath = path.join(dir, 'session.json');
-        return this._loadSessionFile(state, filePath);
-    }
 
-    /**
-     * Resume a specific session by ID.
-     */
-    _resumeById(state, dir, sessionId) {
-        // Check if it is the current session.json
-        const mainFile = path.join(dir, 'session.json');
-        try {
-            const data = JSON.parse(fs.readFileSync(mainFile, 'utf-8'));
-            if (data.id === sessionId) {
-                return this._loadSessionFile(state, mainFile);
-            }
-        } catch { /* continue searching */ }
-
-        // Check archived sessions
-        const archiveFile = path.join(dir, `session-${sessionId}.json`);
-        try {
-            return this._loadSessionFile(state, archiveFile);
-        } catch {
-            return false;
-        }
-    }
-
-    /**
-     * Load a session from a file path.
-     */
-    _loadSessionFile(state, filePath) {
         try {
             const raw = fs.readFileSync(filePath, 'utf-8');
             const session = JSON.parse(raw);
 
-            // Restore all messages so the conversation continues
             state.messages = session.messages || [];
             state.turnCount = session.turnCount || 0;
             state.tokenUsage = session.tokenUsage || { input: 0, output: 0 };
             if (session.model) state.model = session.model;
-            if (session.systemPrompt) state.systemPrompt = session.systemPrompt;
 
             this.sessionId = session.id;
             this.conversationId = session.conversationId;
@@ -166,65 +84,6 @@ export class SessionManager {
         }
     }
 
-    /**
-     * List recent sessions for the current project.
-     * @param {number} [limit=10]
-     * @returns {Array<{id, projectDir, startedAt, savedAt, model, turnCount, messageCount}>}
-     */
-    listSessions(limit = 10) {
-        const dir = this.getSessionDir();
-        const historyFile = path.join(dir, 'sessions-history.json');
-        try {
-            const history = JSON.parse(fs.readFileSync(historyFile, 'utf-8'));
-            return history.slice(-limit).reverse();
-        } catch {
-            // Try loading the single session.json as fallback
-            const mainFile = path.join(dir, 'session.json');
-            try {
-                const data = JSON.parse(fs.readFileSync(mainFile, 'utf-8'));
-                return [{
-                    id: data.id,
-                    projectDir: data.projectDir,
-                    startedAt: data.startedAt,
-                    savedAt: data.savedAt,
-                    model: data.model,
-                    turnCount: data.turnCount,
-                    messageCount: (data.messages || []).length,
-                }];
-            } catch {
-                return [];
-            }
-        }
-    }
-
-    /**
-     * Check if there is a resumable session for the current project.
-     * @returns {{ resumable: boolean, session?: object }}
-     */
-    checkResumable() {
-        const dir = this.getSessionDir();
-        const filePath = path.join(dir, 'session.json');
-        try {
-            const raw = fs.readFileSync(filePath, 'utf-8');
-            const session = JSON.parse(raw);
-            const age = Date.now() - new Date(session.savedAt).getTime();
-            // Only resumable if saved within 24h
-            if (age < 86400000) {
-                return {
-                    resumable: true,
-                    session: {
-                        id: session.id,
-                        savedAt: session.savedAt,
-                        turnCount: session.turnCount,
-                        messageCount: (session.messages || []).length,
-                        model: session.model,
-                    },
-                };
-            }
-        } catch { /* no session */ }
-        return { resumable: false };
-    }
-
     /**
      * Export session for teleport (transfer between machines).
      * @param {object} state - agent loop state