crabcode 0.1.5__tar.gz → 0.1.6__tar.gz

crabcode-0.1.6/.github/workflows/computer-use.yml

@@ -0,0 +1,43 @@
+name: Shared Computer Use
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  native:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-14, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: cargo test --locked --workspace
+        working-directory: packages/computer-use
+      - run: node packages/computer-use/scripts/build.mjs --debug
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install -e . build hatchling pytest pefile
+      - run: python -m pytest tests/test_cli_computer_use.py tests/test_computer_use_packaging.py -q
+      - name: Build and verify Python platform wheel
+        shell: bash
+        run: |
+          export CRABCODE_COMPUTER_USE_BUNDLE="$PWD/packages/computer-use/dist/$(node -p 'process.platform + "-" + process.arch')"
+          python -m build --wheel --no-isolation
+          python packages/computer-use/scripts/check-wheel.py dist
+      - run: npm ci
+        working-directory: packages/vscode
+      - run: npm run build
+        working-directory: packages/vscode
+      - run: node --test tests/computerUse*.test.cjs
+        working-directory: packages/vscode
+      - run: npm ci
+        working-directory: packages/vscode/computer-use
+      - run: npm run build
+        working-directory: packages/vscode/computer-use

crabcode-0.1.6/.github/workflows/python-publish.yml

@@ -0,0 +1,125 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: universal
+            os: ubuntu-latest
+          - name: darwin-arm64
+            os: macos-15
+          - name: darwin-x64
+            os: macos-15-intel
+          - name: win32-x64
+            os: windows-latest
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Check version metadata
+        run: python scripts/sync_version.py --check
+
+      - uses: actions/setup-node@v4
+        if: matrix.name != 'universal'
+        with:
+          node-version: '22'
+
+      - name: Import macOS signing identity when configured
+        if: runner.os == 'macOS'
+        shell: bash
+        env:
+          SIGNING_CERTIFICATE: ${{ secrets.CRABCODE_SIGNING_CERTIFICATE_P12_BASE64 }}
+          SIGNING_PASSWORD: ${{ secrets.CRABCODE_SIGNING_CERTIFICATE_PASSWORD }}
+        run: |
+          if [ -z "$SIGNING_CERTIFICATE" ]; then exit 0; fi
+          python - <<'PY'
+          import base64, os
+          from pathlib import Path
+          (Path(os.environ['RUNNER_TEMP']) / 'crabcode-signing.p12').write_bytes(base64.b64decode(os.environ['SIGNING_CERTIFICATE']))
+          PY
+          keychain="$RUNNER_TEMP/crabcode-signing.keychain-db"
+          keychain_password="$(openssl rand -base64 32)"
+          security create-keychain -p "$keychain_password" "$keychain"
+          security unlock-keychain -p "$keychain_password" "$keychain"
+          security import "$RUNNER_TEMP/crabcode-signing.p12" -k "$keychain" -P "$SIGNING_PASSWORD" -T /usr/bin/codesign
+          security set-key-partition-list -S apple-tool:,apple: -k "$keychain_password" "$keychain" >/dev/null
+          security list-keychains -d user -s "$keychain" login.keychain-db
+          rm "$RUNNER_TEMP/crabcode-signing.p12"
+
+      - name: Build bundled Computer Use component
+        if: matrix.name != 'universal'
+        env:
+          MACOSX_DEPLOYMENT_TARGET: '11.0'
+          CRABCODE_SIGNING_IDENTITY: ${{ secrets.CRABCODE_SIGNING_IDENTITY }}
+        run: node packages/computer-use/scripts/build.mjs
+
+      - name: Install Python build tools
+        run: python -m pip install build pefile
+
+      - name: Build universal wheel and source distribution
+        if: matrix.name == 'universal'
+        run: python -m build
+
+      - name: Build platform wheel with Computer Use
+        if: matrix.name != 'universal'
+        env:
+          CRABCODE_COMPUTER_USE_BUNDLE: ${{ github.workspace }}/packages/computer-use/dist/${{ matrix.name }}
+        run: python -m build --wheel
+
+      - name: Verify native payload and wheel metadata
+        if: matrix.name != 'universal'
+        run: |
+          python packages/computer-use/scripts/check-wheel.py dist
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists-${{ matrix.name }}
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/crabcode
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          pattern: release-dists-*
+          merge-multiple: true
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

{crabcode-0.1.5 → crabcode-0.1.6}/.github/workflows/windows-compat.yml

@@ -24,8 +24,9 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: '22'
-      - run: python -m pip install -e . fastapi pypdf python-multipart
+      - run: python -m pip install -e . fastapi pypdf python-multipart pytest
       - run: python -m unittest discover -s tests -p "test_windows*.py" -v
+      - run: python -m pytest tests/test_cli_computer_use.py -q
 
   windows-clients:
     runs-on: windows-latest
@@ -46,6 +47,10 @@ jobs:
         working-directory: packages/vscode
       - run: npx tsc --noEmit
         working-directory: packages/vscode
+      - run: npm run computer-use:build -- --debug
+        working-directory: packages/desktop
+      - run: cargo test --locked --workspace
+        working-directory: packages/computer-use
       - run: cargo test --locked
         working-directory: packages/desktop/src-tauri
       - run: cargo test --locked windows_credentials_survive_a_new_entry -- --ignored

crabcode-0.1.6/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.egg
+.mypy_cache/
+.ruff_cache/
+.crabcode/
+.claude/
+.DS_Store
+theme-samples
+node_modules
+target/
+packages/computer-use/target-*/
+packages/desktop/src-tauri/gen/schemas/
+packages/desktop/src-tauri/resources/computer-use/
+packages/vscode/resources/computer-use/
+packages/vscode/computer-use/resources/computer-use/
+packages/vscode/computer-use/*.vsix
+_native

{crabcode-0.1.5 → crabcode-0.1.6}/PKG-INFO

@@ -1,17 +1,19 @@
 Metadata-Version: 2.5
 Name: crabcode
-Version: 0.1.5
+Version: 0.1.6
 Summary: CrabCode - AI coding assistant in the terminal
 Requires-Python: >=3.10
 Requires-Dist: anthropic>=0.40.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: mcp>=1.0.0
 Requires-Dist: openai>=1.50.0
+Requires-Dist: pillow>=11.3.0
 Requires-Dist: prompt-toolkit>=3.0.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: tiktoken>=0.7.0
 Requires-Dist: typer>=0.12.0
+Requires-Dist: tzdata>=2024.1; sys_platform == 'win32'
 Requires-Dist: websockets>=12.0
 Provides-Extra: all
 Requires-Dist: agent-client-protocol>=0.9.0; extra == 'all'

{crabcode-0.1.5 → crabcode-0.1.6}/README.md

@@ -48,7 +48,7 @@ the provider-specific keys below).
 
 ```bash
 # Install packages in editable mode
-pip install -e packages/core packages/cli packages/search
+pip install -e packages/core packages/cli packages/search packages/debugger crabcode-gateway
 # Minimal install (core + cli only, no semantic search)
 pip install -e packages/core packages/cli
 # Browser automation dependency
@@ -69,6 +69,9 @@ echo "explain this codebase" | crabcode -p
 # Interactive REPL
 crabcode
 
+# Full Access for this run (skip tool permission prompts)
+crabcode --yolo
+
 # Resume last session
 crabcode --continue      # or -c
 
@@ -81,6 +84,34 @@ newline. You can also press **Esc**, then **Enter** to insert a newline. The
 input frame grows with newlines and wrapped text, and scrolls with the cursor
 when it fills the terminal. These keys also work while the agent is running.
 
+### Follow-up behavior
+
+CLI, VS Code, and Desktop support follow-ups during an active run. **Queue** is
+the default: messages run as separate turns in FIFO order after the current turn
+finishes. **Steer** adds guidance at a safe boundary of the current run, such as
+after a tool returns. Queued input retains its images and attached context.
+
+Choose the default in **Desktop Settings → General → Conversation → Follow-up
+behavior** or in VS Code's `crabcode.followUpMode` setting. Queued messages appear
+in cards above the composer, with Steer and Delete actions. The menu offers Edit
+message (recall the message and its images into the composer) and Disable queue
+(switch future messages to Steer while keeping existing queued messages).
+During a run, Enter uses the default and Cmd+Enter
+(macOS) / Ctrl+Enter (Windows/Linux) uses the opposite for just that message;
+Shift+Enter inserts a newline. Idle input keeps the configured send shortcut.
+
+In the CLI, `/follow-up queue` and `/follow-up steer` save `follow_up_mode` in user
+settings. Ctrl+S sends the opposite while working; Ctrl+Enter also works in
+terminals that report extended key codes. Ctrl+J and Alt/Opt+Enter insert newlines.
+With an empty composer and no pending image attachments, Ctrl+S / Ctrl+Enter
+moves the oldest queued message into steering, including its original attachments,
+without changing the default mode. Use `/queue` to list pending messages and
+`/queue steer [number]` to promote one (the number defaults to 1). Promotion applies
+at the next safe boundary; it leaves the message queued if steering fails.
+
+Stopping or failing a run discards its unexecuted queue. Desktop and VS Code keep
+that input available to restore into the composer; CLI prints the unsent messages.
+
 ### Persistent Goals
 
 Use `/goal` to keep a measurable objective active across turns, compaction, and
@@ -202,7 +233,7 @@ Use HTTPS/WSS whenever the gateway is exposed beyond the local machine.
 | Endpoint | Method | Description |
 | ---------- | -------- | ------------- |
 | `/health` | GET | Health check with the CrabCode version and gateway protocol compatibility range |
-| `/session/new` | POST | Create a session; accepts `cwd` plus optional `model`, `provider`, `base_url`, `api_format`, and `model_profile` overrides |
+| `/session/new` | POST | Create a session; accepts `cwd` plus optional model overrides and composer-control defaults (`reasoning_effort`, `ultra_mode`, `mode`, `permission_mode`) |
 | `/session/send` | POST | Send a message (starts query loop, events via SSE) |
 | `/session/interrupt` | POST | Interrupt current turn |
 | `/session/compact` | POST | Trigger manual compaction |
@@ -276,7 +307,7 @@ Use HTTPS/WSS whenever the gateway is exposed beyond the local machine.
 `delete_model`, `upsert_group`, `delete_group`, `set_default_model`, and
 `clear_default_model`. Mutations target `userSettings`, `projectSettings`, or
 `localSettings`; project layers require a `cwd` within the Gateway workspace.
-`POST /config/runtime-settings` accepts `set_snapshot`, `add_extra_tool`, and
+`POST /config/runtime-settings` accepts `set_snapshot`, `set_computer_use_mode`, `add_extra_tool`, and
 `remove_extra_tool`, using the same configuration layers. Disabling snapshots
 skips only the file-system copy; conversation checkpoints are still persisted.
 
@@ -474,7 +505,9 @@ Or configure in `~/.crabcode/settings.json`:
 | `reasoning_effort` | Model reasoning effort. OpenAI Responses/Codex sends it as `reasoning.effort`; Anthropic sends supported values as `output_config.effort`. When set, it takes precedence over the Codex `thinking_budget` mapping. Options: `none` \| `minimal` \| `low` \| `medium` \| `high` \| `xhigh` \| `max` (availability depends on the model/provider). | — |
 | `max_tokens` | Maximum output tokens | `16384` |
 | `timeout` | API call timeout in seconds (prevents hanging on slow/unresponsive APIs) | `300` |
-| `max_retries` | Automatic reconnect attempts for transient API, rate-limit, timeout, and server failures. Requests are replayed only when no response content or tool call has arrived. | `5` |
+| `request_max_retries` | Silent HTTP request retry budget for transport failures and 5xx responses (429 is handled by the stream layer). Uses 200 ms exponential backoff with jitter. | `4` |
+| `max_retries` | Stream reconnect budget. Retryable drops are replayed from the last completed response item with 200 ms exponential backoff and jitter; completed tool calls are never executed twice. | `5` |
+| `unbounded_connection_retries` | Keep retrying connection-establishment failures with a separate 5–60 second exponential backoff. Stream failures still use `max_retries`. | `true` |
 | `context_window` | Override the model's context window size (tokens). Used when auto-detection fails or is inaccurate — see [Context Window](#context-window) below. | auto-detected |
 | `prompt_cache_key` | Prompt cache routing key for OpenAI Responses/Codex requests; defaults to `http_headers.session_id` when omitted | — |
 | `prompt_cache_retention` | OpenAI Responses/Codex prompt cache retention policy: `in_memory` \| `24h` | — |
@@ -563,7 +596,7 @@ If your model is not in the built-in table and you don't set an override, the 20
 
 **Automatic compaction**
 
-CrabCode estimates the complete request (system prompts, messages, tool calls/results, tool schemas, and image payloads). It normally compacts before input exceeds `context_window - max(max_tokens, 20000)`:
+CrabCode measures the complete request (system prompts, messages, tool calls/results, tool schemas, and image payloads). It automatically compacts when input exceeds `context_window - max(max_tokens, compact_buffer_tokens)`, with `compact_buffer_tokens` defaulting to `20000`:
 
 1. Incrementally summarizes the full older history into a structured, resumable checkpoint
 2. Keeps up to two complete recent user turns, so tool calls are never separated from their results
@@ -572,6 +605,18 @@ CrabCode estimates the complete request (system prompts, messages, tool calls/re
 
 Use `/compact [optional instructions]` to trigger it manually. `auto_compact_enabled` controls automatic compaction. `max_context_length` can set an earlier input threshold, but it cannot raise the threshold past the provider-safe limit.
 
+Configure these top-level fields in `settings.json`:
+
+```json
+{
+  "auto_compact_enabled": true,
+  "compact_buffer_tokens": 30000,
+  "max_context_length": null
+}
+```
+
+The buffer must be a nonnegative integer. Setting it to `0` still reserves the model's `max_tokens` output allowance. A `null` `max_context_length` uses the automatic threshold. All three controls are available in the VS Code chat settings menu → **上下文压缩** (or the **CrabCode：打开上下文压缩设置** command) and Desktop **Settings → 运行与工具 → 上下文压缩**. Both let you choose the configuration layer to save. Changes apply from the next conversation turn; a running turn keeps its original settings.
+
 > **Note**: Compaction uses the configured API model. If checkpoint generation fails, CrabCode keeps the original conversation unchanged; it never replaces history with a lossy fallback. Provider overflow recovery is attempted only before response output has started, avoiding duplicate tool calls after a partial response.
 
 ### Logging
@@ -714,9 +759,15 @@ crabcode --model-profile smart    # short: -M smart
 /model fast         # switch to the "fast" (ollama) profile
 /model smart        # switch to the "smart" (anthropic) profile
 /model code         # switch to the "code" (openai) profile
+/add                # guided menu: add a model or shared group
+/add model          # open the add-model wizard directly
+/del group          # choose and delete a group definition
 ```
 
 Switching does not clear conversation history — you can mix models freely within a single session.
+The `/add` and `/del` wizards let you choose user, shared-project, or local-project
+settings. Delete targets show their exact source layer; the active model (or its
+group) is protected until you switch away from it.
 
 ## Built-in Tools
 
@@ -724,6 +775,7 @@ Switching does not clear conversation history — you can mix models freely with
 | ------ | ------ | ------------- |
 | `Bash` | write | Execute shell commands |
 | `Read` | read | Read file contents |
+| `apply_patch` | write | Apply a validated, transactional multi-file patch |
 | `Write` | write | Create or overwrite files |
 | `StrReplace` | write | Precise in-place text replacement |
 | `Glob` | read | Find files by glob pattern |
@@ -734,6 +786,13 @@ Switching does not clear conversation history — you can mix models freely with
 | `Memory` | write | Store and retrieve persistent notes |
 | `AskUser` | read | Present choices to the user and wait for selection |
 
+For shell-level discovery, CrabCode reports whether `rg`, `sed`, and `find` are
+available in the runtime environment. The agent prefers dedicated tools for
+ordinary reads and searches, while using read-only `sed -n` pipelines and
+advanced `find` predicates when they are a better fit. File mutation stays in
+`apply_patch`, `Edit`, or `Write`, so changes retain permission checks, snapshots,
+and diff rendering.
+
 ### Lint
 
 The `Lint` tool runs the appropriate linter for the given language automatically:
@@ -872,7 +931,7 @@ In **pipe mode** (non-interactive), the first option is auto-selected.
 
 The `WebSearch` tool searches the public web and returns compact search results with titles, URLs, and snippets.
 
-- **Default provider order** — Tavily first when `TAVILY_API_KEY` is configured, otherwise DuckDuckGo HTML search
+- **Default provider order** — Tavily first when `TAVILY_API_KEY` is configured, otherwise DuckDuckGo HTML search. If DuckDuckGo answers with a bot check, search continues with Bing RSS instead of reporting an empty result.
 - **Offline behavior** — if CrabCode cannot detect outbound network access during session startup, `WebSearch` is disabled for that session and is not exposed to the model
 - **Permission behavior** — `WebSearch` is read-only, but still asks for confirmation before each network request
 
@@ -893,7 +952,7 @@ Configure via `tool_settings.WebSearch` in `settings.json`:
 
 Supported `provider` values:
 
-- `"auto"` — use Tavily when configured, otherwise DuckDuckGo; if Tavily fails at runtime, retry with DuckDuckGo once
+- `"auto"` — use Tavily when configured, otherwise DuckDuckGo; if Tavily fails at runtime, retry with DuckDuckGo once. If DuckDuckGo is blocked, fall back to Bing for about ten minutes
 - `"tavily"` — require a configured API key and use Tavily only
 - `"ddg"` — use DuckDuckGo only
 
@@ -963,9 +1022,38 @@ Default permission behavior:
 
 `headless` in `tool_settings.Browser` is the session default. The tool input can override it per session when calling `create_session`.
 
+### Computer Use modes
+
+Desktop, VS Code and CLI share a standalone Computer Use component; VS Code and CLI do not require Crab Desktop. Platform wheels for macOS (Apple Silicon / Intel) and Windows x64 include the native executor, so `pip install crabcode` installs it too. The first CLI session automatically deploys it to the shared user directory, with no extra installation command or launch flag. Interactive and pipe sessions connect automatically; status appears in `/status`, without a startup banner. `crabcode computer-use status` also checks capabilities directly. Source installs and universal wheels can reuse an existing component; otherwise, use a platform wheel containing the native executor.
+
+In VS Code, `crabcode.computerUseEnabled` is enabled by default; set it to `false` to disable Computer Use. Use the Computer Use status-bar menu for monitoring, permission settings and refresh. Remote SSH/WSL/container windows use the **local** CrabCode Computer Use companion extension. On macOS, grant **Crab Computer Use** Accessibility and Screen Recording permissions. See [component development and packaging](packages/computer-use/README.md).
+
+Once a host is connected, agents can inspect and operate desktop applications. Background application mode is the default:
+
+```json
+{
+  "computer_use": {
+    "target_scope": "app_window",
+    "delivery_policy": "allow_foreground"
+  }
+}
+```
+
+On AX-capable macOS hosts, window observation prefers the accessibility tree. `observe` accepts `observation: "auto" | "ax" | "screenshot"`; `auto` falls back to pixels when AX observation is unavailable. Use `press`, `set_value` (replace the whole text value), or `perform_action` with the returned `window_id`, `snapshot_id` and `element_id`. Element actions return a fresh bounded tree; screenshots are optional. References belong to one host connection, session and agent, expire, and are invalidated by new observations, input and release. Re-observe stale references; never replay uncertain AX input through mouse events. An AX acknowledgement alone does not prove the intended effect occurred. After fresh observation, the agent can make a new decision using a screenshot: coordinate clicks on the new protocol use mouse delivery directly, without another AXPress attempt. `allow_foreground` also permits explicitly focusing the window before re-observing.
+
+AX observation works with Accessibility permission even without Screen Recording. Strict background still requires an exact validated OS/app/element/action profile and sampled isolation checks: currently TextEdit 1.20/415 on macOS build 25D125 arm64 supports `AXValue` on its `AXTextArea`. Other AX actions remain gated, and existing validated coordinate routes remain available. Desktop scope and local VMs retain their screenshot workflow.
+
+The target and delivery policy are independent:
+
+- `app_window` observes and sends input to a selected macOS application window; call `list_windows` first and pass `window_id`. `desktop` controls the complete desktop and real pointer/keyboard.
+- `strict_background` uses process/window-targeted delivery and does not expose `focus_window`; applications that require activation may ignore input.
+- `allow_foreground` permits activating the target window when background delivery is insufficient and can interrupt the current user. Desktop scope requires this policy.
+
+Crab Desktop can write these settings from **Settings → Runtime & Tools → Computer Use** at the user, project, or project-local layer. VS Code can explicitly override them with `crabcode.computerUseTargetScope` and `crabcode.computerUseDeliveryPolicy`. Delivery policy is independent of tool approval modes such as Full Access, and the agent cannot override it inside an action.
+
 ### Diff Display
 
-When the agent edits a file via `StrReplace` or `Write`, the terminal shows a compact inline diff:
+When the agent edits files via `apply_patch`, `Edit`, or `Write`, the terminal shows an inline diff. Multi-file patches are grouped by file:
 
 ```
   ✎ src/auth.py  lines 42–55  (+8 / -3)
@@ -980,7 +1068,7 @@ CrabCode automatically tracks file-system changes made during a session, allowin
 **How it works:**
 
 1. Every time you create a checkpoint (`/checkpoint`), CrabCode takes a snapshot of the working directory state using git internals (or file-copy fallback for non-git projects).
-2. Tools that modify files (`Edit`, `Write`, `Bash`) also record per-file snapshots before each change.
+2. Tools that modify files (`apply_patch`, `Edit`, `Write`, `Bash`) also record per-file snapshots before each change.
 3. You can revert to any checkpoint to restore both the conversation **and** the files to that point.
 
 **Commands:**
@@ -1032,6 +1120,14 @@ section can add or remove `extra_tools` import paths on the remote Gateway;
 the package must be installed in that Gateway environment. Changes apply to
 new sessions or after reconnecting an existing session.
 
+For a local Gateway, Desktop also exposes **Settings → General → CrabCode
+Suite**. Automatic provisioning keeps the lightweight `gateway` extra, while
+the explicit installer keeps Gateway selected and lets you independently check
+Search, Debugger, and future optional capabilities. The VS Code extension uses
+the same multi-select model through **CrabCode: Select and Install Local Suite**
+and the link beside `crabcode.gatewayAutoInstall`. Remote environments are
+never modified by either client.
+
 **Gateway API:**
 
 | Endpoint | Method | Description |
@@ -1053,6 +1149,8 @@ new sessions or after reconnecting an existing session.
 | `/logs --clear <name>` | Clear a specific log file |
 | `/model` | Open a searchable model picker organized by group; ↑/↓ select, Enter switches, Esc cancels, Tab and ←/→ filter groups |
 | `/model <name>` | Switch to a named model from `settings.models` |
+| `/add [model\|group]` | Add a named model or shared group with a guided, searchable configuration wizard |
+| `/del [model\|group]` | Delete a model or group from a selected writable settings layer |
 | `/effort` | Show the active reasoning effort |
 | `/effort <none\|minimal\|low\|medium\|high\|xhigh\|max>` | Set reasoning effort for subsequent requests in the current runtime session |
 | `/ultra` | Toggle ultra mode for subsequent requests |
@@ -1219,6 +1317,11 @@ Set `"default_mode": "run_everything"` to skip all permission prompts and execut
 
 `"run_everything": true` is still accepted for backward compatibility.
 
+Use `crabcode --yolo` to enable Full Access for a single CLI run without
+changing `settings.json`. It also works with `-p`, `--continue`, and `--resume`,
+and overrides configured permission rules and AI review using the existing
+`run_everything` mode. Plan mode and Computer Use delivery policy still apply.
+
 > **Use with caution.** In this mode CrabCode will run shell commands and write files without asking.
 
 The VS Code extension defaults to **Follow settings** (`crabcode.permissionMode: "default"`),
@@ -1235,6 +1338,32 @@ Settings are loaded from multiple layers (later overrides earlier):
 4. Flag settings
 5. `~/.crabcode/managed-settings.json` (policy)
 
+### Custom Global Directory
+
+Set `CRABCODE_HOME` before starting CrabCode to use a different global directory:
+
+```bash
+export CRABCODE_HOME="$HOME/.config/crabcode"
+crabcode
+```
+
+On PowerShell: `$env:CRABCODE_HOME = "$HOME\.config\crabcode"`.
+Use an absolute directory path or `~/...`. An unset or blank value defaults to
+`~/.crabcode`; relative paths are rejected so different projects share the same
+global directory.
+
+The directory contains `settings.json`, `managed-settings.json`, global MCP
+configuration, skills, `CLAUDE.md`, memories, sessions, usage and schedules.
+Desktop settings and its managed Gateway environment also use this directory.
+Project-level `.crabcode` directories and explicit feature-specific paths
+(such as `CRABCODE_DOCUMENT_ENGINE_HOME`) keep their existing behavior.
+References to `~/.crabcode` elsewhere in this guide describe the default location.
+
+Existing files are not moved automatically; copy them into the new directory if
+you want to reuse them. Restart CLI, Gateway and Desktop after changing the
+variable, and ensure each process inherits it. A desktop app launched from the
+system launcher may not inherit variables exported in a terminal.
+
 ### Ultra Mode
 
 Set the top-level `ultra_mode` field to make the main model proactively split non-trivial work across many sub-agents and run independent tasks in parallel:
@@ -1259,7 +1388,7 @@ By default, CrabCode does not apply a global timeout to tool calls. Set the top-
 
 Omit `tool_call_timeout` or set it to `null` to disable the global limit. Filesystem and tool-specific timeouts, such as `filesystem_timeout`, `Bash.timeout`, or `agent.timeout`, still apply independently and may be shorter.
 
-The shared filesystem tool timeout defaults to **3600 seconds** for Read, Write, Edit, Glob, Grep, and Bash. Set the top-level `filesystem_timeout` field in `~/.crabcode/settings.json` or the project's `.crabcode/settings.json` to change it:
+The shared filesystem tool timeout defaults to **3600 seconds** for Read, apply_patch, Write, Edit, Glob, Grep, and Bash. Set the top-level `filesystem_timeout` field in `~/.crabcode/settings.json` or the project's `.crabcode/settings.json` to change it:
 
 ```json
 {
@@ -1967,8 +2096,11 @@ Each section field follows the same rule:
 | `output_efficiency` | Verbosity rules | built-in |
 | `session_guidance` | Session-level hints | built-in |
 | `agent_prompt` | System prompt for spawned sub-agents | built-in |
+| `compact_prompt` | Checkpoint prompt for manual and automatic context compaction | built-in |
 | `extra_sections` | Additional sections appended after all built-in ones | `[]` |
 
+The desktop **Settings → Prompts** panel and VS Code's **CrabCode: Open Prompt Settings** command include a context-compaction prompt field. Load the built-in text to edit it, then save the template for subsequent manual, automatic, and sub-agent compaction. Clear the field or use **Restore default**, then save, to restore the built-in prompt. This field follows the active template and is included in template JSON imports and exports. Temporary instructions after `/compact` are still appended to the compaction prompt.
+
 You can also build profiles in code using `PromptProfile` from `crabcode_core.prompts.profile`:
 
 ```python
@@ -1994,7 +2126,7 @@ crabcode/
 │   │   ├── types/              # Pydantic types (Message, Tool, Event, Config)
 │   │   ├── api/                # API adapters (Anthropic, OpenAI, Router)
 │   │   ├── query/              # Agentic turn loop
-│   │   ├── tools/              # Built-in tools (Bash, Read, Edit, Write, Grep, Glob, WebSearch, Lint, Memory, AskUser, Team)
+│   │   ├── tools/              # Built-in tools (Bash, Read, apply_patch, Edit, Write, Grep, Glob, WebSearch, Lint, Memory, AskUser, Team)
 │   │   ├── team/               # Agent Teams (models, message bus, manager, inbox, recovery, bridge)
 │   │   ├── lsp/                # LSP client integration (LSPClient, LSPManager, diagnostics formatting, server registry)
 │   │   ├── skills/             # Skill loading + auto-trigger matching (SkillDefinition, load_skills, auto_match)