fix: install via venv on Linux

.claude/INSTALL.md

@@ -13,7 +13,9 @@ Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/c
 ## What this installs
 
 - Git repo: `~/.claude/agent-environment-backup`
-- Python package: editable user install of `agent-environment-backup`
+- Python package:
+  - Windows: editable user install
+  - macOS/Linux: repo-local virtual environment at `~/.claude/agent-environment-backup/.venv`
 - Skill link: `~/.claude/skills/claude-code-environment-backup -> ~/.claude/agent-environment-backup/skills/claude-code-environment-backup`
 
 The install does not create a backup, restore anything, change providers, write hooks, or upload data.
@@ -85,6 +87,7 @@ Run this shell block exactly:
 set -euo pipefail
 
 repo_root="$HOME/.claude/agent-environment-backup"
+venv_dir="$repo_root/.venv"
 skills_root="$HOME/.claude/skills"
 skill_namespace="$skills_root/claude-code-environment-backup"
 skill_source="$repo_root/skills/claude-code-environment-backup"
@@ -114,16 +117,22 @@ if [ -e "$repo_root" ]; then
   exit 1
 fi
 
-if [ -e "$skill_namespace" ]; then
+if [ -e "$skill_namespace" ] || [ -L "$skill_namespace" ]; then
   echo "The skill namespace link already exists. Remove it or follow UNINSTALL.md before reinstalling." >&2
   exit 1
 fi
 
 mkdir -p "$skills_root"
 git clone https://github.com/gaoguobin/codex-environment-backup.git "$repo_root"
-"$python_cmd" -m pip install --user -e "$repo_root"
+"$python_cmd" -m venv "$venv_dir" || {
+  echo "Failed to create a virtual environment. On Debian/Ubuntu, install python3-venv for your Python version, then rerun this INSTALL.md." >&2
+  exit 1
+}
+venv_python="$venv_dir/bin/python"
+cli="$venv_dir/bin/agent-environment-backup"
+"$venv_python" -m pip install -e "$repo_root"
 ln -s "$skill_source" "$skill_namespace"
-"$python_cmd" -m agent_environment_backup --profile claude-code doctor
+"$cli" --profile claude-code doctor
 ```
 
 ## After install

.claude/UNINSTALL.md

@@ -78,30 +78,6 @@ set -euo pipefail
 
 repo_root="$HOME/.claude/agent-environment-backup"
 skill_namespace="$HOME/.claude/skills/claude-code-environment-backup"
-python_cmd="${PYTHON:-}"
-
-if [ -z "$python_cmd" ]; then
-  for candidate in python3 python; do
-    if command -v "$candidate" >/dev/null 2>&1 && "$candidate" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)' >/dev/null 2>&1; then
-      python_cmd="$candidate"
-      break
-    fi
-  done
-fi
-
-if [ -z "$python_cmd" ]; then
-  for candidate in python3 python; do
-    if command -v "$candidate" >/dev/null 2>&1; then
-      python_cmd="$candidate"
-      break
-    fi
-  done
-fi
-
-if [ -n "$python_cmd" ]; then
-  "$python_cmd" -m pip uninstall -y agent-environment-backup
-fi
-
 if [ -L "$skill_namespace" ] || [ -e "$skill_namespace" ]; then
   rm "$skill_namespace"
 fi

.claude/UPDATE.md

@@ -78,6 +78,7 @@ Run this shell block exactly:
 set -euo pipefail
 
 repo_root="$HOME/.claude/agent-environment-backup"
+venv_dir="$repo_root/.venv"
 skill_namespace="$HOME/.claude/skills/claude-code-environment-backup"
 skill_source="$repo_root/skills/claude-code-environment-backup"
 python_cmd="${PYTHON:-}"
@@ -106,7 +107,19 @@ if [ ! -d "$repo_root" ]; then
 fi
 
 git -C "$repo_root" pull --ff-only
-"$python_cmd" -m pip install --user -e "$repo_root"
+if [ ! -d "$venv_dir" ]; then
+  "$python_cmd" -m venv "$venv_dir" || {
+    echo "Failed to create a virtual environment. On Debian/Ubuntu, install python3-venv for your Python version, then rerun this UPDATE.md." >&2
+    exit 1
+  }
+fi
+venv_python="$venv_dir/bin/python"
+cli="$venv_dir/bin/agent-environment-backup"
+"$venv_python" -m pip install -e "$repo_root"
+
+if [ -L "$skill_namespace" ] && [ ! -e "$skill_namespace" ]; then
+  rm "$skill_namespace"
+fi
 
 if [ ! -e "$skill_namespace" ]; then
   mkdir -p "$(dirname "$skill_namespace")"
@@ -121,7 +134,7 @@ elif [ ! -f "$skill_namespace/SKILL.md" ]; then
   fi
 fi
 
-"$python_cmd" -m agent_environment_backup --profile claude-code doctor
+"$cli" --profile claude-code doctor
 ```
 
 Report the final structural doctor JSON. If skill files changed or the skill link was newly created, explicitly tell the user:

.codex/INSTALL.md

@@ -13,7 +13,9 @@ Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/c
 ## What this installs
 
 - Git repo: `~/.codex/codex-environment-backup`
-- Python package: editable user install of `codex-environment-backup`
+- Python package:
+  - Windows: editable user install
+  - macOS/Linux: repo-local virtual environment at `~/.codex/codex-environment-backup/.venv`
 - Skill namespace link: `~/.agents/skills/codex-environment-backup -> ~/.codex/codex-environment-backup/skills`
 
 The install does not create a backup, restore anything, change providers, write hooks, or upload data.
@@ -86,6 +88,7 @@ Run this shell block exactly:
 set -euo pipefail
 
 repo_root="$HOME/.codex/codex-environment-backup"
+venv_dir="$repo_root/.venv"
 skills_root="$HOME/.agents/skills"
 skill_namespace="$skills_root/codex-environment-backup"
 
@@ -114,16 +117,22 @@ if [ -e "$repo_root" ]; then
   exit 1
 fi
 
-if [ -e "$skill_namespace" ]; then
+if [ -e "$skill_namespace" ] || [ -L "$skill_namespace" ]; then
   echo "The skill namespace link already exists. Remove it or follow UNINSTALL.md before reinstalling." >&2
   exit 1
 fi
 
 mkdir -p "$skills_root"
 git clone https://github.com/gaoguobin/codex-environment-backup.git "$repo_root"
-"$python_cmd" -m pip install --user -e "$repo_root"
+"$python_cmd" -m venv "$venv_dir" || {
+  echo "Failed to create a virtual environment. On Debian/Ubuntu, install python3-venv for your Python version, then rerun this INSTALL.md." >&2
+  exit 1
+}
+venv_python="$venv_dir/bin/python"
+cli="$venv_dir/bin/agent-environment-backup"
+"$venv_python" -m pip install -e "$repo_root"
 ln -s "$repo_root/skills" "$skill_namespace"
-"$python_cmd" -m agent_environment_backup --profile codex doctor
+"$cli" --profile codex doctor
 ```
 
 ## After install

.codex/UNINSTALL.md

@@ -80,30 +80,6 @@ set -euo pipefail
 
 repo_root="$HOME/.codex/codex-environment-backup"
 skill_namespace="$HOME/.agents/skills/codex-environment-backup"
-python_cmd="${PYTHON:-}"
-
-if [ -z "$python_cmd" ]; then
-  for candidate in python3 python; do
-    if command -v "$candidate" >/dev/null 2>&1 && "$candidate" -c 'import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)' >/dev/null 2>&1; then
-      python_cmd="$candidate"
-      break
-    fi
-  done
-fi
-
-if [ -z "$python_cmd" ]; then
-  for candidate in python3 python; do
-    if command -v "$candidate" >/dev/null 2>&1; then
-      python_cmd="$candidate"
-      break
-    fi
-  done
-fi
-
-if [ -n "$python_cmd" ]; then
-  "$python_cmd" -m pip uninstall -y agent-environment-backup codex-environment-backup
-fi
-
 if [ -L "$skill_namespace" ] || [ -e "$skill_namespace" ]; then
   rm "$skill_namespace"
 fi

.codex/UPDATE.md

@@ -72,6 +72,7 @@ Run this shell block exactly:
 set -euo pipefail
 
 repo_root="$HOME/.codex/codex-environment-backup"
+venv_dir="$repo_root/.venv"
 skill_namespace="$HOME/.agents/skills/codex-environment-backup"
 python_cmd="${PYTHON:-}"
 
@@ -99,15 +100,34 @@ if [ ! -d "$repo_root" ]; then
 fi
 
 git -C "$repo_root" pull --ff-only
-"$python_cmd" -m pip uninstall -y codex-environment-backup
-"$python_cmd" -m pip install --user -e "$repo_root"
+if [ ! -d "$venv_dir" ]; then
+  "$python_cmd" -m venv "$venv_dir" || {
+    echo "Failed to create a virtual environment. On Debian/Ubuntu, install python3-venv for your Python version, then rerun this UPDATE.md." >&2
+    exit 1
+  }
+fi
+venv_python="$venv_dir/bin/python"
+cli="$venv_dir/bin/agent-environment-backup"
+"$venv_python" -m pip install -e "$repo_root"
+
+if [ -L "$skill_namespace" ] && [ ! -e "$skill_namespace" ]; then
+  rm "$skill_namespace"
+fi
 
 if [ ! -e "$skill_namespace" ]; then
   mkdir -p "$(dirname "$skill_namespace")"
   ln -s "$repo_root/skills" "$skill_namespace"
+elif [ ! -f "$skill_namespace/codex-environment-backup/SKILL.md" ]; then
+  if [ -L "$skill_namespace" ]; then
+    rm "$skill_namespace"
+    ln -s "$repo_root/skills" "$skill_namespace"
+  else
+    echo "Existing skill namespace is not a link and does not contain codex-environment-backup/SKILL.md: $skill_namespace" >&2
+    exit 1
+  fi
 fi
 
-"$python_cmd" -m agent_environment_backup --profile codex doctor
+"$cli" --profile codex doctor
 ```
 
 Report the final structural doctor JSON. The default doctor intentionally skips external `codex` commands to avoid sandbox noise before restart. If skill files changed or the skill link was newly created, explicitly tell the user in the user's language:

README.md

@@ -105,8 +105,10 @@ Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/c
 ```
 
 The install flow clones this repository to `~/.codex/codex-environment-backup`,
-installs the Python package in editable user mode, and links the bundled skill
-into `~/.agents/skills`.
+installs the Python package, and links the bundled skill into `~/.agents/skills`.
+On macOS and Linux, the install uses a repo-local virtual environment at
+`~/.codex/codex-environment-backup/.venv` so it does not depend on system
+`pip`, `pip --user`, or `--break-system-packages`.
 
 After installation, restart Codex App and return to the same conversation, or
 open a new Codex CLI process. Then ask:
@@ -125,7 +127,8 @@ Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/c
 
 The install flow clones this repository to `~/.claude/agent-environment-backup`,
 installs the same Python package, and links the Claude Code skill into
-`~/.claude/skills`.
+`~/.claude/skills`. On macOS and Linux, this also uses a repo-local virtual
+environment at `~/.claude/agent-environment-backup/.venv`.
 
 After installation, restart Claude Code or open a new CLI process. Then ask:
 
@@ -221,6 +224,9 @@ Backups are written under `~/Documents/CodexBackups` by default:
 ~/Documents/CodexBackups/codex-backup-YYYYMMDD-HHMMSS.tar.gz.sha256
 ```
 
+If `~/Documents` already exists but is not a writable directory, the CLI falls
+back to `~/CodexBackups`.
+
 For Claude Code, the default home is `~/.claude` and backups are written under
 `~/Documents/ClaudeCodeBackups`:
 
@@ -230,6 +236,9 @@ For Claude Code, the default home is `~/.claude` and backups are written under
 ~/Documents/ClaudeCodeBackups/claude-code-backup-YYYYMMDD-HHMMSS.tar.gz.sha256
 ```
 
+If `~/Documents` already exists but is not a writable directory, the CLI falls
+back to `~/ClaudeCodeBackups`.
+
 Each backup directory contains:
 
 ```text
@@ -272,6 +281,9 @@ only recovery path for lost Codex history or provider state.
 - SQLite databases ending in `.sqlite` are copied with the Python `sqlite3`
   backup API and then checked with `PRAGMA integrity_check`.
 - Windows uses junctions for skill installation; macOS and Linux use symlinks.
+- macOS and Linux installs use a repo-local `.venv` to avoid Ubuntu/Debian
+  PEP 668 `externally-managed-environment` failures and systems without
+  `python3 -m pip`.
 
 `codex-fast-proxy` is optional. If `python -m codex_fast_proxy` is available in
 the current Python environment, `doctor` records safe `status` / `doctor`
@@ -339,6 +351,18 @@ Codex cannot operate.
 Use Python 3.11 or newer. Prefer `python3` when it exists; on Windows, `python`
 is acceptable when it points to Python 3.11+.
 
+After a Codex install on macOS/Linux, the natural-language skill uses:
+
+```text
+~/.codex/codex-environment-backup/.venv/bin/agent-environment-backup
+```
+
+After a Claude Code install on macOS/Linux, it uses:
+
+```text
+~/.claude/agent-environment-backup/.venv/bin/agent-environment-backup
+```
+
 ```powershell
 # Codex (default profile)
 python -m agent_environment_backup doctor
@@ -408,6 +432,8 @@ Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/c
 ```
 
 安装只会安装仓库、Python 包和 skill 链接；不会创建备份、恢复文件、修改 provider、写 hooks 或上传数据。
+在 macOS/Linux 上，安装使用仓库内 `.venv`，不依赖系统 `python3 -m pip`、`pip --user` 或
+`--break-system-packages`。
 
 Claude Code：
 
@@ -423,6 +449,8 @@ Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/c
 备份当前 Claude Code 环境
 ```
 
+在 macOS/Linux 上，Claude Code 安装同样使用 `~/.claude/agent-environment-backup/.venv`。
+
 ### 日常用法
 
 对 Codex 说：
@@ -497,12 +525,24 @@ Windows 上通常类似：
 C:\Users\<you>\Documents\CodexBackups
 ```
 
+如果 `~/Documents` 已存在但不是可写目录，会回退到：
+
+```text
+~/CodexBackups
+```
+
 Claude Code 默认读取 `~/.claude`，默认备份位置是：
 
 ```text
 ~/Documents/ClaudeCodeBackups
 ```
 
+如果 `~/Documents` 已存在但不是可写目录，会回退到：
+
+```text
+~/ClaudeCodeBackups
+```
+
 ### 备份保留
 
 工具不会默认删除旧备份。正式安装后，建议先完成一次新的正式备份，并确认：
@@ -573,6 +613,18 @@ SkillsMP 或其它 marketplace 收录，也不声称是 OpenAI 官方 plugin 或
 CLI 留给高级用户、CI、smoke test、自动化和 Codex 自身不可用时的恢复兜底。普通备份、检查和列出备份
 不应要求用户手动运行命令。
 
+macOS/Linux 正式安装后，Codex skill 优先使用：
+
+```text
+~/.codex/codex-environment-backup/.venv/bin/agent-environment-backup
+```
+
+Claude Code skill 优先使用：
+
+```text
+~/.claude/agent-environment-backup/.venv/bin/agent-environment-backup
+```
+
 ```powershell
 # Codex（默认 profile）
 python -m agent_environment_backup doctor