@cjhyy/code-shell 0.1.5 → 0.1.7

package/dist/settings/schema.d.ts

@@ -219,16 +219,16 @@ export declare const SettingsSchema: z.ZodObject<{
         args?: string[] | undefined;
         headers?: Record<string, string> | undefined;
         command?: string | undefined;
-        transport?: "stdio" | "sse" | "streamable-http" | "inprocess" | undefined;
         env?: Record<string, string> | undefined;
+        transport?: "stdio" | "sse" | "streamable-http" | "inprocess" | undefined;
     }, {
         name: string;
         url?: string | undefined;
         args?: string[] | undefined;
         headers?: Record<string, string> | undefined;
         command?: string | undefined;
-        transport?: "stdio" | "sse" | "streamable-http" | "inprocess" | undefined;
         env?: Record<string, string> | undefined;
+        transport?: "stdio" | "sse" | "streamable-http" | "inprocess" | undefined;
     }>>>;
     instructions: z.ZodDefault<z.ZodObject<{
         fileName: z.ZodDefault<z.ZodString>;
@@ -303,6 +303,28 @@ export declare const SettingsSchema: z.ZodObject<{
     }, {
         format?: "text" | "json" | "jsonl" | "stream-json" | undefined;
     }>>;
+    /**
+     * OS-level sandbox for shell-tool execution. "auto" picks per platform:
+     * Seatbelt on macOS, bubblewrap on Linux when installed, otherwise off.
+     * Defaults are applied per Engine run depending on headless vs REPL —
+     * see Engine.run() and run.ts.
+     */
+    sandbox: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<["off", "auto", "seatbelt", "bwrap"]>>;
+        writableRoots: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        deniedReads: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        network: z.ZodOptional<z.ZodEnum<["allow", "deny"]>>;
+    }, "strip", z.ZodTypeAny, {
+        mode?: "auto" | "off" | "seatbelt" | "bwrap" | undefined;
+        writableRoots?: string[] | undefined;
+        deniedReads?: string[] | undefined;
+        network?: "allow" | "deny" | undefined;
+    }, {
+        mode?: "auto" | "off" | "seatbelt" | "bwrap" | undefined;
+        writableRoots?: string[] | undefined;
+        deniedReads?: string[] | undefined;
+        network?: "allow" | "deny" | undefined;
+    }>>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     agent: z.ZodDefault<z.ZodObject<{
         preset: z.ZodDefault<z.ZodString>;
@@ -520,16 +542,16 @@ export declare const SettingsSchema: z.ZodObject<{
         args?: string[] | undefined;
         headers?: Record<string, string> | undefined;
         command?: string | undefined;
-        transport?: "stdio" | "sse" | "streamable-http" | "inprocess" | undefined;
         env?: Record<string, string> | undefined;
+        transport?: "stdio" | "sse" | "streamable-http" | "inprocess" | undefined;
     }, {
         name: string;
         url?: string | undefined;
         args?: string[] | undefined;
         headers?: Record<string, string> | undefined;
         command?: string | undefined;
-        transport?: "stdio" | "sse" | "streamable-http" | "inprocess" | undefined;
         env?: Record<string, string> | undefined;
+        transport?: "stdio" | "sse" | "streamable-http" | "inprocess" | undefined;
     }>>>;
     instructions: z.ZodDefault<z.ZodObject<{
         fileName: z.ZodDefault<z.ZodString>;
@@ -604,6 +626,28 @@ export declare const SettingsSchema: z.ZodObject<{
     }, {
         format?: "text" | "json" | "jsonl" | "stream-json" | undefined;
     }>>;
+    /**
+     * OS-level sandbox for shell-tool execution. "auto" picks per platform:
+     * Seatbelt on macOS, bubblewrap on Linux when installed, otherwise off.
+     * Defaults are applied per Engine run depending on headless vs REPL —
+     * see Engine.run() and run.ts.
+     */
+    sandbox: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<["off", "auto", "seatbelt", "bwrap"]>>;
+        writableRoots: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        deniedReads: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        network: z.ZodOptional<z.ZodEnum<["allow", "deny"]>>;
+    }, "strip", z.ZodTypeAny, {
+        mode?: "auto" | "off" | "seatbelt" | "bwrap" | undefined;
+        writableRoots?: string[] | undefined;
+        deniedReads?: string[] | undefined;
+        network?: "allow" | "deny" | undefined;
+    }, {
+        mode?: "auto" | "off" | "seatbelt" | "bwrap" | undefined;
+        writableRoots?: string[] | undefined;
+        deniedReads?: string[] | undefined;
+        network?: "allow" | "deny" | undefined;
+    }>>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     agent: z.ZodDefault<z.ZodObject<{
         preset: z.ZodDefault<z.ZodString>;
@@ -821,16 +865,16 @@ export declare const SettingsSchema: z.ZodObject<{
         args?: string[] | undefined;
         headers?: Record<string, string> | undefined;
         command?: string | undefined;
-        transport?: "stdio" | "sse" | "streamable-http" | "inprocess" | undefined;
         env?: Record<string, string> | undefined;
+        transport?: "stdio" | "sse" | "streamable-http" | "inprocess" | undefined;
     }, {
         name: string;
         url?: string | undefined;
         args?: string[] | undefined;
         headers?: Record<string, string> | undefined;
         command?: string | undefined;
-        transport?: "stdio" | "sse" | "streamable-http" | "inprocess" | undefined;
         env?: Record<string, string> | undefined;
+        transport?: "stdio" | "sse" | "streamable-http" | "inprocess" | undefined;
     }>>>;
     instructions: z.ZodDefault<z.ZodObject<{
         fileName: z.ZodDefault<z.ZodString>;
@@ -905,6 +949,28 @@ export declare const SettingsSchema: z.ZodObject<{
     }, {
         format?: "text" | "json" | "jsonl" | "stream-json" | undefined;
     }>>;
+    /**
+     * OS-level sandbox for shell-tool execution. "auto" picks per platform:
+     * Seatbelt on macOS, bubblewrap on Linux when installed, otherwise off.
+     * Defaults are applied per Engine run depending on headless vs REPL —
+     * see Engine.run() and run.ts.
+     */
+    sandbox: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodEnum<["off", "auto", "seatbelt", "bwrap"]>>;
+        writableRoots: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        deniedReads: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        network: z.ZodOptional<z.ZodEnum<["allow", "deny"]>>;
+    }, "strip", z.ZodTypeAny, {
+        mode?: "auto" | "off" | "seatbelt" | "bwrap" | undefined;
+        writableRoots?: string[] | undefined;
+        deniedReads?: string[] | undefined;
+        network?: "allow" | "deny" | undefined;
+    }, {
+        mode?: "auto" | "off" | "seatbelt" | "bwrap" | undefined;
+        writableRoots?: string[] | undefined;
+        deniedReads?: string[] | undefined;
+        network?: "allow" | "deny" | undefined;
+    }>>;
 }, z.ZodTypeAny, "passthrough">>;
 export type ValidatedSettings = z.infer<typeof SettingsSchema>;
 export declare function validateSettings(raw: unknown): ValidatedSettings;

package/dist/tool-summary-5UE62VU4.js

@@ -0,0 +1,2 @@
+import {b}from'./chunk-B7K2OWKC.js';import {h,a}from'./chunk-3QP5BQ3L.js';h();var p='Generate a very brief (under 40 chars) summary of what these tools did. Use past tense, commit-subject style. Examples: "Read 3 config files", "Fixed import in auth.ts", "Searched for API endpoints". Respond with ONLY the summary text, nothing else.';async function d(r,a,l){if(r.length===0)return null;try{let e=[];for(let t=0;t<r.length;t++){let s=r[t],o=a[t],u=JSON.stringify(s.args).slice(0,200),c=(o?.result??o?.error??"").slice(0,300);e.push(`Tool: ${s.toolName}(${u}) \u2192 ${c}`);}return (await l(p,e.join(`
+`)))?.trim()||null}catch(e){return b.warn("tool_summary.failed",{error:e.message}),null}}a(d,"generateToolUseSummary");export{d as generateToolUseSummary};

package/dist/tool-system/builtin/bash.d.ts

@@ -1,6 +1,12 @@
 /**
  * Built-in Bash shell command execution tool.
+ *
+ * Spawns commands under an optional OS-level sandbox (Seatbelt on macOS,
+ * bubblewrap on Linux). The sandbox is selected by the Engine and handed
+ * down via ToolContext.sandbox. Without a sandbox we fall back to the
+ * historical behavior — plain shell spawn in the user's environment.
  */
+import type { ToolContext } from "../context.js";
 import type { ToolDefinition } from "../../types.js";
 export declare const bashToolDef: ToolDefinition;
-export declare function bashTool(args: Record<string, unknown>): Promise<string>;
+export declare function bashTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/context.d.ts

@@ -16,6 +16,7 @@ import type { LLMConfig, StreamCallback } from "../types.js";
 import type { ModelPool } from "../llm/model-pool.js";
 import type { ToolRegistry } from "./registry.js";
 import type { AgentPresetName } from "../preset/index.js";
+import type { SandboxBackend } from "./sandbox/index.js";
 /** One choice in a multiple-choice AskUserQuestion. */
 export interface AskUserChoice {
     label: string;
@@ -86,6 +87,12 @@ export interface ToolContext {
     askUser?: AskUserFn;
     /** Sub-agent spawner (Agent tool). Undefined → Agent tool unavailable. */
     subAgentSpawner?: SubAgentSpawner;
+    /**
+     * Active sandbox backend for the Bash tool. Undefined falls back to "off"
+     * (plain spawn). Headless runs default to an OS-level sandbox; the REPL
+     * defaults to off because a human is in the loop to approve commands.
+     */
+    sandbox?: SandboxBackend;
     /** Optional cancellation signal for the whole turn. */
     signal?: AbortSignal;
 }

package/dist/tool-system/investigation-guard.d.ts

@@ -28,6 +28,15 @@ export declare class InvestigationGuard {
     private turnHasText;
     private turnHasSideEffect;
     private lastReminderSilent;
+    /**
+     * Soft mode replaces hard blocks (3rd-read dedupe) with a stronger
+     * reminder. Used in headless runs (`code-shell run …`) where there is
+     * no human to retry the task, so an unattended automation should not
+     * be killed by the guard — it should still get the signal to change
+     * strategy, but the tool call goes through.
+     */
+    private softMode;
+    setSoftMode(soft: boolean): void;
     preToolCheck(call: ToolCall): GuardDecision | undefined;
     noteText(text: string | undefined): void;
     noteToolResult(_call: ToolCall, _result: ToolResult): void;

package/dist/tool-system/sandbox/bwrap.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Linux bubblewrap backend.
+ *
+ * bwrap creates a fresh mount namespace, then bind-mounts only what we tell
+ * it. We bind / read-only and overlay writableRoots as read-write. PID,
+ * IPC, UTS, cgroup namespaces are unshared. Network is shared unless
+ * config.network === "deny".
+ *
+ * Sensitive directories listed in deniedReads are shadowed with a tmpfs so
+ * the inner process literally cannot see them even though `/` is mounted.
+ */
+import type { SandboxBackend, SandboxConfig } from "./index.js";
+export declare function createBwrapBackend(config: SandboxConfig): SandboxBackend;

package/dist/tool-system/sandbox/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Sandbox backends for shell command execution.
+ *
+ * We wrap Bash-tool commands in an OS-level sandbox so a misbehaving (or
+ * prompt-injected) model can't reach beyond the workspace. The sandbox runs
+ * the user's command inside an isolated process tree with restricted file
+ * and (optionally) network access. The Engine itself is NOT sandboxed; only
+ * the spawned shell is. File-editing tools (Edit/Write) keep going through
+ * the application-layer permission gate.
+ *
+ * Backends are platform-specific:
+ *   - "seatbelt"  macOS sandbox-exec, built into macOS, zero install
+ *   - "bwrap"     Linux bubblewrap, requires `apt install bubblewrap`
+ *   - "off"       passthrough, no sandboxing (current behavior)
+ *
+ * "auto" picks per platform at startup; falls back to "off" with a warning
+ * when no sandbox is available.
+ */
+export type SandboxMode = "off" | "auto" | "seatbelt" | "bwrap";
+export type SandboxNetworkPolicy = "allow" | "deny";
+export interface SandboxConfig {
+    mode: SandboxMode;
+    writableRoots: string[];
+    deniedReads: string[];
+    network: SandboxNetworkPolicy;
+}
+export interface SandboxBackend {
+    /** Resolved backend name — "off" means no sandboxing. */
+    name: "off" | "seatbelt" | "bwrap";
+    /**
+     * Decide the binary + argv that should actually be spawned to run `command`
+     * under this sandbox. The shell still interprets `command`; we only swap
+     * the outer process.
+     */
+    wrap(command: string, opts: {
+        cwd: string;
+        shell: string;
+    }): {
+        file: string;
+        args: string[];
+    };
+    /**
+     * If `stderr` looks like a sandbox denial, return a short hint string that
+     * the Bash tool will append to its result so the model understands why.
+     */
+    hintForBlockedOutput?(stderr: string): string | undefined;
+}
+/**
+ * Detect which sandbox mechanisms are available on the current host. Used by
+ * "auto" mode and surfaced to the user via /sandbox status if desired.
+ */
+export declare function detectSandboxCapabilities(): {
+    seatbelt: boolean;
+    bwrap: boolean;
+};
+/**
+ * Expand `~` and `${workspace}` placeholders against the live cwd and home.
+ */
+export declare function expandPath(p: string, cwd: string): string;
+export declare function expandConfig(config: SandboxConfig, cwd: string): SandboxConfig;
+export declare function defaultSandboxConfig(mode?: SandboxMode): SandboxConfig;
+/**
+ * Resolve the active backend given user config + the current host.
+ *
+ *   "off"      → off backend
+ *   "seatbelt" → seatbelt if available, else throws (explicit choice)
+ *   "bwrap"    → bwrap if available, else throws
+ *   "auto"     → seatbelt on macOS, bwrap on Linux with bwrap installed,
+ *                else off + console warning
+ */
+export declare function resolveSandboxBackend(config: SandboxConfig, cwd: string): Promise<SandboxBackend>;

package/dist/tool-system/sandbox/off.d.ts

@@ -0,0 +1,2 @@
+import type { SandboxBackend } from "./index.js";
+export declare function createOffBackend(): SandboxBackend;

package/dist/tool-system/sandbox/seatbelt.d.ts

@@ -0,0 +1,18 @@
+/**
+ * macOS Seatbelt backend.
+ *
+ * Builds a sandbox-exec profile that:
+ *   - Allows reading most of the filesystem (denying everything breaks tooling)
+ *   - Denies reads of sensitive credential directories
+ *   - Restricts writes to the workspace + writableRoots
+ *   - Optionally denies outbound network
+ *
+ * The profile is written to a fresh temp file per command (cheap; users can
+ * have arbitrary writableRoots so we can't cache). The spawned process and
+ * its entire subprocess tree inherit the profile via XNU's sandbox framework.
+ *
+ * sandbox-exec is technically deprecated by Apple but remains the only
+ * working OS-level sandbox on macOS and is what Codex CLI / Cursor use today.
+ */
+import type { SandboxBackend, SandboxConfig } from "./index.js";
+export declare function createSeatbeltBackend(config: SandboxConfig): SandboxBackend;

package/dist/types.d.ts

@@ -169,6 +169,7 @@ export interface TaskInfo {
 export type StreamEvent = {
     type: "session_started";
     sessionId: string;
+    promptTokens: number;
 } | {
     type: "stream_request_start";
     turnNumber: number;
@@ -176,6 +177,7 @@ export type StreamEvent = {
 } | {
     type: "text_delta";
     text: string;
+    tokens?: number;
     agentId?: string;
 } | {
     type: "tool_use_start";
@@ -258,6 +260,8 @@ export interface LLMResponse {
 export interface LLMStreamChunk {
     type: "text" | "tool_use_start" | "tool_use_delta" | "tool_use_end" | "stop";
     text?: string;
+    /** Token count for this text delta, when provider can compute it. */
+    tokens?: number;
     toolCall?: Partial<ToolCall>;
     stopReason?: string;
 }

package/dist/ui/components/SessionPicker.d.ts

@@ -1,6 +1,8 @@
 export interface SessionPickerEntry {
     sessionId: string;
     startedAt: number;
+    /** Last activity time — used to sort and display the row. */
+    lastActiveAt?: number;
     turnCount: number;
     preview?: string;
     cwd?: string;

package/dist/ui/components/SpinnerWithVerb.d.ts

@@ -5,9 +5,9 @@ import { type MutableRefObject } from "react";
 export type SpinnerMode = "responding" | "tool-use" | "thinking";
 interface SpinnerWithVerbProps {
     mode: SpinnerMode;
-    streamingCharsRef?: MutableRefObject<number>;
+    streamingTokensRef?: MutableRefObject<number>;
     runStartRef?: MutableRefObject<number>;
     thinkingContent?: string;
 }
-export declare function SpinnerWithVerb({ mode, streamingCharsRef, runStartRef, thinkingContent, }: SpinnerWithVerbProps): import("react/jsx-runtime").JSX.Element;
+export declare function SpinnerWithVerb({ mode, streamingTokensRef, runStartRef, thinkingContent, }: SpinnerWithVerbProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/ui/components/StatusLine.d.ts

@@ -17,8 +17,8 @@ interface StatusLineProps {
     maxContextTokens?: number;
     gitBranch?: string;
     isRunning?: boolean;
-    streamingCharsRef?: MutableRefObject<number>;
+    streamingTokensRef?: MutableRefObject<number>;
     runStartRef?: MutableRefObject<number>;
 }
-export declare function StatusLine({ model, effort, tokens, cost, sessionId, baseContextTokens, maxContextTokens, gitBranch, isRunning, streamingCharsRef, runStartRef, }: StatusLineProps): import("react/jsx-runtime").JSX.Element;
+export declare function StatusLine({ model, effort, tokens, cost, sessionId, baseContextTokens, maxContextTokens, gitBranch, isRunning, streamingTokensRef, runStartRef, }: StatusLineProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/updater-OCNU2K2Z.js

@@ -0,0 +1 @@
+export{f as __internal,a as checkForUpdate,c as getAutoUpdateDisabledReason,e as getCurrentVersion,b as getUpdateAvailable,d as scheduleAutoInstallOnExit}from'./chunk-TKJA6W36.js';import'./chunk-3QP5BQ3L.js';

package/package.json

@@ -1,31 +1,27 @@
 {
   "name": "@cjhyy/code-shell",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Code Shell — general-purpose agent orchestration framework with a terminal coding preset",
   "type": "module",
-  "main": "./dist/index.cjs",
+  "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": "./dist/index.js"
     },
     "./run": {
       "types": "./dist/run/index.d.ts",
-      "import": "./dist/run/index.js",
-      "require": "./dist/run/index.cjs"
+      "import": "./dist/run/index.js"
     },
     "./arena": {
       "types": "./dist/arena/index.d.ts",
-      "import": "./dist/arena/index.js",
-      "require": "./dist/arena/index.cjs"
+      "import": "./dist/arena/index.js"
     },
     "./product": {
       "types": "./dist/product/index.d.ts",
-      "import": "./dist/product/index.js",
-      "require": "./dist/product/index.cjs"
+      "import": "./dist/product/index.js"
     },
     "./package.json": "./package.json"
   },
@@ -62,6 +58,7 @@
   "files": [
     "dist",
     "scripts/check-node.cjs",
+    "skills-builtin",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -94,6 +91,7 @@
     "emoji-regex": "^10.6.0",
     "get-east-asian-width": "^1.5.0",
     "glob": "^11.0.0",
+    "gpt-tokenizer": "^3.4.0",
     "indent-string": "^5.0.0",
     "lodash-es": "^4.17.23",
     "marked": "^17.0.5",

package/skills-builtin/codeshell-help.md

@@ -0,0 +1,135 @@
+---
+name: codeshell-help
+description: Use when the user asks how to use code-shell itself — slash commands, login/model setup, settings.json keys, hooks, MCP servers, debugging flags, or "how do I X in code-shell". Skip for general programming questions.
+when_to_use: User asks about code-shell features, configuration, slash commands, or runtime behavior. Not for code questions in the user's own project.
+---
+
+# Using code-shell
+
+You are running inside **code-shell**, a terminal coding agent. This skill answers user questions about code-shell itself. Quote sections directly where helpful. If a topic isn't covered, say so — don't invent commands.
+
+## Getting started
+
+- `code-shell` — start an interactive REPL in the current directory.
+- `code-shell run "<prompt>"` — one-shot non-interactive run, prints final answer and exits.
+- `code-shell runs <sid>` — resume a saved session by id.
+- First launch shows an onboarding flow that walks through provider + model setup.
+
+## Slash commands (run inside the REPL)
+
+Type `/` and the menu appears. The full list:
+
+### Core
+- `/help` — show the slash menu.
+- `/exit` — quit the REPL.
+- `/clear` — clear the conversation (keeps session id).
+- `/compact` — manually trigger context compaction.
+- `/status` — current model, effort, token usage, working dir.
+- `/version` — code-shell version.
+- `/cost` — token cost summary for the session.
+- `/sid` — print the current session id.
+- `/session` — open the session picker.
+- `/resume` — resume the most recent session.
+- `/diff` — show working-tree diff.
+- `/tasks` — current task list (TaskCreate/TaskUpdate state).
+- `/tools` — list available tools.
+- `/memory` — open the per-project memory file.
+- `/export markdown` — export the current conversation to a markdown file.
+
+### Models / providers
+- `/login` — add a new provider + model via the unified ProviderModelFlow.
+- `/logout` — remove a provider's stored credentials.
+- `/model` — quick-switch the active model.
+- `/models` — open the ModelManager (add, refresh, delete providers and models).
+
+### Configuration
+- `/config` — open `settings.json` for the active scope.
+- `/permissions` — manage tool permission rules.
+- `/hooks` — list hooks configured in settings.
+- `/mcp` — list and manage MCP servers.
+- `/skills` — list discovered skills.
+- `/effort` — set reasoning effort (low / medium / high) for reasoning models.
+
+### Git / review
+- `/commit` — agent drafts a commit from staged changes.
+- `/branch` — branch operations.
+- `/review` — review pending changes.
+- `/pr-comments` — fetch GitHub PR comments.
+- `/autofix-pr` — apply review suggestions.
+- `/security-review` — run a security-focused review of pending changes.
+
+### Misc
+- `/init` — scaffold or refresh `CODESHELL.md` / project rules based on repo state.
+- `/copy` — copy last response to clipboard.
+- `/undo` — undo the most recent file edit done by the agent.
+- `/update` — check for and install code-shell updates (auto-installs on exit when npm prefix is writable).
+- `/log` — open the session log file.
+- `/files` — list files the agent has touched this session.
+- `/release-notes` — show CHANGELOG for the running version.
+- `/feedback` — open the feedback URL.
+- `/voice` — voice input (if enabled).
+
+## Provider + model setup
+
+code-shell uses a **two-layer config**: `providers[]` holds credentials and base URLs; `models[]` references a provider by key.
+
+- New users: `/login` runs the full wizard — pick provider kind (anthropic / openai / openrouter / deepseek / custom), enter API key, optional base URL, then pick a model from the fetched list.
+- Existing users with the legacy flat `models[]` shape: auto-migrated on startup with a `.bak` snapshot written next to `settings.json`.
+- Refresh a provider's model list: `/models` → select provider → Refresh. Cached for 7 days under `~/.code-shell/cache/`.
+
+## settings.json — key fields
+
+Located at `~/.code-shell/settings.json` (user scope) or `.code-shell/settings.json` (project scope, takes precedence).
+
+- `providers[]` — `[{ key, kind, baseUrl, apiKey }]`. Source of credentials.
+- `models[]` — `[{ id, providerKey, displayName, contextLength, ... }]`.
+- `model` — the default active model id.
+- `autoUpdates` — `false` disables the background updater.
+- `permissions` — allow/deny rules for the Bash tool and others.
+- `hooks` — shell commands to run on events (SessionStart, PreToolUse, etc.).
+- `mcpServers` — `{ name: { command, args, env } }` map of MCP servers.
+
+## Hooks
+
+Hooks are shell commands the harness runs on events. Configured in `settings.json` under `hooks`. Common events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`. Use them for automated behaviors ("each time X happens, run Y") — memory or preferences can't do this because the model doesn't fire actions on schedule, the harness does.
+
+## MCP servers
+
+`code-shell` speaks the Model Context Protocol. Add servers in `settings.json` under `mcpServers`. Each entry is a stdio command code-shell spawns; its tools/resources become available to the agent automatically. List with `/mcp`.
+
+## Debugging
+
+- `CODE_SHELL_DEV=1 code-shell` — dev mode: enables the per-session verbose recorder (JSONL traces under `log/<date>/session-<sid>.jsonl`, 7-day retention), disables auto-update, shows extra UI.
+- `--debug` flag has the same effect as `CODE_SHELL_DEV=1`.
+- Logs: `~/.code-shell/log/` for general logs; per-session JSONL traces appear there when dev mode is on.
+- Investigation guard: re-reading the same file 3× is hard-blocked. 4+ consecutive read-only tool calls inject a "change strategy" reminder. This is intentional — break the loop, don't fight it.
+- Update install log: `~/.code-shell/update.log`.
+
+## Memory
+
+code-shell has a per-project memory system at `.code-shell/memory/` (relative to project root) and a global one at `~/.code-shell/memory/`. The `MEMORY.md` index is auto-loaded into context every session. Individual memory files are loaded on demand. Edit with `/memory` or directly.
+
+## Skills
+
+Skills are markdown files with frontmatter that get discovered automatically. Locations scanned:
+- `<cwd>/.code-shell/skills/` — project-level
+- `<cwd>/.claude/skills/` — project-level (Claude Code compat)
+- `~/.code-shell/skills/` — user-level
+- `~/.claude/skills/` — user-level (Claude Code compat)
+- Built-in skills shipped with the package (e.g. this one).
+
+List discovered skills with `/skills`. Invoke a skill with the `Skill` tool by name. Frontmatter `description` tells the model when to use it.
+
+## Common questions
+
+**"How do I switch models?"** — `/model <id>` or pick from `/models`.
+
+**"How do I add a new provider?"** — `/login`, then follow the wizard. Or edit `settings.json` `providers[]` directly.
+
+**"Why is auto-update not working?"** — `/update` shows the disabled reason. Common: dev build, `DISABLE_AUTOUPDATER=1`, `settings.autoUpdates: false`, or the npm global prefix isn't writable (use the shown `sudo` command).
+
+**"Where's my session saved?"** — `~/.code-shell/sessions/<sid>/`. State, messages, and tool results all there.
+
+**"How do I see what tools an agent has?"** — `/tools`.
+
+**"How do I limit what Bash commands the agent can run?"** — `/permissions` or edit `settings.permissions` directly.

package/dist/anthropic-IBTI4WL2.cjs

@@ -1,10 +0,0 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});
-
-var _chunkYIQBXAYUcjs = require('./chunk-YIQBXAYU.cjs');
-require('./chunk-7EG3V4JY.cjs');
-require('./chunk-2YW4FPFG.cjs');
-require('./chunk-IK4EWJBP.cjs');
-require('./chunk-KS3RYAYL.cjs');
-
-
-exports.AnthropicClient = _chunkYIQBXAYUcjs.AnthropicClient;

package/dist/anthropic-PRZZKHEZ.js

@@ -1,10 +0,0 @@
-import {
-  AnthropicClient
-} from "./chunk-ZBPSQCPU.js";
-import "./chunk-6S4BJ65N.js";
-import "./chunk-SFXHZSRF.js";
-import "./chunk-BXCY2FSE.js";
-import "./chunk-MD32R22I.js";
-export {
-  AnthropicClient
-};