batipanel 0.4.33 → 0.4.35

package/README.md

@@ -18,47 +18,59 @@
 
 ---
 
-One command to launch a fully configured, beautifully themed multi-panel development environment with **Claude Code**, **Git UI**, **system monitor**, **file browser**, and more.
+**One command. Full dev environment.** Install Claude Code, Git UI, system monitor, file browser — and manage them all as tmux sessions with a single keystroke.
+
+```bash
+curl -fsSL batipanel.com/install.sh | bash
+```
+
+<!-- GIF: before/after demo on a fresh Linux server -->
+<!-- <p align="center"><img src="docs/demo.gif" width="720" alt="batipanel demo"/></p> -->
+
+### What happens when you run this:
+
+1. **Auto-installs everything** — tmux, Claude Code, lazygit, btop, yazi, eza (+ Nerd Font on macOS)
+2. **Configures your terminal** — themed prompt, powerline glyphs, color scheme
+3. **One command to start** — `b myproject` launches a multi-panel workspace:
 
 ```
 ┌────────────────────────────────┬──────────────┐
-│                                │ system       │
-│  Claude Code (AI assistant)    │ monitor      │
-│                                ├──────────────┤
-│                                │ file tree    │
+│                                │   monitor    │
+│     Claude Code (AI)           ├──────────────┤
+│                                │  file tree   │
 │                                ├──────────────┤
 │                                │ remote ctrl  │
 ├───────────┬────────────────────┴──────────────┤
-│ git       │ terminal           │ logs         │
+│    git    │   terminal         │    logs      │
 └───────────┴────────────────────┴──────────────┘
 ```
 
+4. **Session persistence** — SSH drops? Terminal closed? `b myproject` brings it all back.
+
 ## Quick Start
 
 ```bash
 # Install (pick one)
 curl -fsSL https://batipanel.com/install.sh | bash   # Recommended
-npx batipanel                                         # npm/npx
-brew install batiai/tap/batipanel                      # Homebrew
+npm install -g batipanel                              # npm
+npx batipanel                                         # npx (no install)
 
-# Launch — the setup wizard guides you through everything
-b
+# Start your workspace
+b myproject
 ```
 
-That's it. The wizard asks 2 questions (screen size + workflow) and sets up your workspace.
-
 ---
 
-## Why batipanel?
+## Key Features
 
-| | What it does |
+| | |
 |---|---|
-| **AI-First Workspace** | Claude Code gets 55%+ of screen space. Remote Control panel lets you command AI from any pane. Dual-Claude layout for multi-agent workflows. |
-| **Multi-Panel Dev Tools** | lazygit, btop, yazi, terminal, logs — all auto-launched in themed panels. Missing tools gracefully fallback (btop → htop → top). |
-| **8 Layout Presets** | From 4-panel laptop mode to 8-panel ultrawide. Switch anytime with `b myproject --layout 6panel`. |
-| **Instant Session Resume** | tmux-powered persistence. SSH drops? Terminal closed? `b myproject` brings everything back exactly as you left it. |
-| **8 Color Themes** | Dracula, Nord, Gruvbox, Tokyo Night, Catppuccin, Rose Pine, Kanagawa + default. Powerline-style status bar and shell prompt. Live reload. |
-| **AI Telegram Bot** | Deploy a personal AI bot in Docker with `b server init && b server start`. Zero extra cost for Claude Max users. |
+| **All-in-one install** | One command sets up Claude Code + 5 dev tools + terminal theme. No manual config. |
+| **Session management** | `b start`, `b stop`, `b ls` — manage workspaces like containers. Persistent across disconnects. |
+| **8 layouts** | From 4-panel laptop to 8-panel ultrawide. Switch with `b myproject --layout 6panel`. |
+| **8 color themes** | Dracula, Nord, Gruvbox, Tokyo Night, Catppuccin, Rose Pine, Kanagawa. Live reload with `b theme`. |
+| **Smart fallbacks** | Every tool has a fallback. No btop? Uses htop. No htop? Uses top. Nothing breaks. |
+| **Cross-platform** | macOS (Terminal.app, iTerm2) + Linux (Ubuntu, Amazon Linux, CentOS) + WSL. |
 
 ---
 
@@ -388,7 +400,9 @@ Your projects and settings are always preserved during upgrades.
 
 ---
 
-## AI Telegram Bot (OpenClaw)
+## AI Telegram Bot (OpenClaw) — Experimental
+
+> **Note:** This feature is experimental and under active development. API and configuration may change.
 
 Deploy a personal AI bot in an isolated Docker environment with one command.
 
@@ -441,26 +455,34 @@ All optional tools are auto-installed when possible. Missing tools gracefully fa
 
 ---
 
-## Terminal Compatibility
+## Platform Support
 
-| Platform | Supported Terminals |
-|----------|---------------------|
-| **macOS** | Terminal.app, iTerm2, Alacritty, Kitty, WezTerm, Warp |
-| **Linux** | GNOME Terminal, Konsole, Alacritty, Kitty, WezTerm, xterm |
-| **Windows** | Windows Terminal + WSL2 |
+| Platform | Status | Terminals Tested |
+|----------|--------|------------------|
+| **macOS** | Stable | Terminal.app, iTerm2 |
+| **Ubuntu/Debian** | Stable | GNOME Terminal, default terminal |
+| **Amazon Linux / CentOS** | Beta | default terminal (tmux 2.6+ required, auto-installed) |
+| **Windows** | Beta | Windows Terminal + WSL2 |
+| Other Linux | Community | Alacritty, Kitty, WezTerm, xterm |
 
 ### macOS Terminal.app (built-in)
 
 batipanel works out of the box with macOS's built-in Terminal. The installer automatically:
 
-- Installs **Nerd Font** (MesloLGS NF) via Homebrew
-- Sets the font on your Terminal profile via `osascript`
-- Applies **theme colors** (background, text, cursor) to your profile
+- Creates a dedicated **batipanel** Terminal profile (your original profile is untouched)
+- Installs **Nerd Font** (MesloLGS NF) via Homebrew and sets it on the profile
+- Applies **theme colors** (background, text, cursor)
 
 All layouts, panels, keyboard shortcuts, 256-color themes, Powerline arrows, and session resume work fully.
 
 > **Want true color (24-bit)?** Use [iTerm2](https://iterm2.com) for the richest color experience. Terminal.app supports 256 colors which covers all themes well.
 
+### Linux
+
+The installer auto-installs Nerd Font to `~/.local/share/fonts`. You may need to **select the font manually** in your terminal's preferences (look for "MesloLGS NF" or "MesloLGS Nerd Font").
+
+On distributions with old tmux (e.g. Amazon Linux 2 ships 1.8), the installer will attempt to install tmux 3.x automatically.
+
 <details>
 <summary><b>Troubleshooting</b></summary>
 
@@ -480,6 +502,23 @@ All layouts, panels, keyboard shortcuts, 256-color themes, Powerline arrows, and
 
 ---
 
+## Documentation
+
+| | |
+|---|---|
+| [Getting Started](docs/100-getting-started.md) | Install, first run, activation |
+| [Usage Guide](docs/200-usage-guide.md) | Commands, sessions, project management |
+| [Layouts & Panels](docs/300-layouts-panels.md) | 8 presets, panel types, customization |
+| [Themes](docs/400-themes-appearance.md) | 8 color themes, fonts, prompt styling |
+| [Configuration](docs/500-configuration.md) | config.sh, tmux.conf, env variables |
+| [Supported Tools](docs/600-supported-tools.md) | Claude Code, lazygit, btop, yazi, eza |
+| [Remote & SSH](docs/700-remote-ssh.md) | Server sessions, detach/reattach |
+| [FAQ](docs/800-faq-troubleshooting.md) | Troubleshooting, platform-specific fixes |
+| [Contributing](docs/900-contributing.md) | Dev setup, testing, PR guidelines |
+| [Roadmap](docs/999-roadmap.md) | Planned features, what's next |
+
+---
+
 ## Contributing
 
 Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

package/VERSION

@@ -1 +1 @@
-0.4.33
+0.4.35

package/config/btop/btop.conf

@@ -0,0 +1,8 @@
+# batipanel btop config — compact mode for multi-panel layouts
+# Shows only CPU graph + process list (no memory, network, disk boxes)
+shown_boxes = "cpu proc"
+vim_keys = True
+rounded_corners = True
+theme_background = False
+proc_per_core = False
+update_ms = 2000

package/install.sh

@@ -8,13 +8,15 @@ BATIPANEL_HOME="${BATIPANEL_HOME:-$HOME/.batipanel}"
 
 echo "batipanel - Setting up AI development workspace..."
 
-# detect OS
+# detect OS (used by sourced modules)
+# shellcheck disable=SC2034
 OS="$(uname -s)"
 
 # resolve installer directory (before sourcing modules that use SCRIPT_DIR)
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # shared state: modified by utils.sh install_from_github()
+# shellcheck disable=SC2034
 NEED_LOCAL_BIN_PATH=0
 
 # source modules
@@ -51,6 +53,7 @@ setup_fonts_and_terminal
 
 # === 10. setup shell environment (powerline fonts, prompt theme) ===
 # _sed_i is needed by shell-setup.sh (reuse install.sh's sed_i)
+# shellcheck disable=SC2317
 _sed_i() { sed_i "$@"; }
 export -f _sed_i 2>/dev/null || true
 
@@ -72,6 +75,7 @@ _generate_theme_conf "$BATIPANEL_THEME"
 generate_theme_env "$BATIPANEL_THEME"
 
 # setup shell RC (sources prompt file from .bashrc/.zshrc)
+# shellcheck disable=SC2153  # USER_SHELL and SHELL_RC set by shell-rc.sh
 setup_shell_environment "$USER_SHELL" "$SHELL_RC"
 
 # === done ===
@@ -143,10 +147,11 @@ fi
 # don't exec $SHELL — it breaks /dev/tty when run from curl|bash or subshells
 if [ -z "${npm_lifecycle_event:-}" ]; then
   echo ""
-  echo -e "\033[1;33m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\033[0m"
-  echo -e "\033[1;33m  Activate batipanel (choose one):\033[0m"
+  echo -e "  \033[2m───────────────────────────────────\033[0m"
+  echo -e "  \033[1mNext step\033[0m \033[2m— activate your shell:\033[0m"
   echo ""
-  echo -e "  \033[1;32m▶ exec \$SHELL -l\033[0m        ← paste this"
-  echo -e "  \033[1;32m▶ restart terminal\033[0m       ← or just close & reopen"
-  echo -e "\033[1;33m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\033[0m"
+  echo -e "    \033[36mexec \$SHELL -l\033[0m"
+  echo ""
+  echo -e "  \033[2mor just open a new terminal window.\033[0m"
+  echo -e "  \033[2m───────────────────────────────────\033[0m"
 fi

package/layouts/7panel.sh

@@ -21,8 +21,8 @@ CLAUDE=$(tmux list-panes -t "$SESSION" -F '#{pane_id}' | head -1)
 # Top(70%) | Bottom(30%)
 LAZYGIT=$(_split -v -t "$CLAUDE" -c "$PROJECT" -p 30 -PF '#{pane_id}')
 
-# Top: left(55%) | right(45%)
-BTOP=$(_split -h -t "$CLAUDE" -c "$PROJECT" -p 45 -PF '#{pane_id}')
+# Top: left(60%) | right(40%)
+BTOP=$(_split -h -t "$CLAUDE" -c "$PROJECT" -p 40 -PF '#{pane_id}')
 
 # Right column: 3 rows
 EZA=$(_split -v -t "$BTOP" -c "$PROJECT" -p 67 -PF '#{pane_id}')

package/lib/layout.sh

@@ -75,18 +75,32 @@ init_layout() {
 # Wait for shell init after pane splits
 wait_for_panes() { sleep 0.5; }
 
-# Compatible split-window: try with -p (percentage), fallback without it
+# Compatible split-window: converts -p N to -l N% for tmux 3.x compatibility
 # Usage: same as tmux split-window (drop-in replacement)
 _split() {
-  tmux split-window "$@" 2>/dev/null && return 0
-  # strip -p <N> and retry (tmux versions where -p fails)
-  local args=() skip=0
+  # rewrite args: -p <N> → -l <N>%
+  local args=() skip_next=0
   for a in "$@"; do
-    if (( skip )); then skip=0; continue; fi
-    if [[ "$a" == "-p" ]]; then skip=1; continue; fi
+    if (( skip_next )); then
+      args+=("-l" "${a}%")
+      skip_next=0
+      continue
+    fi
+    if [[ "$a" == "-p" ]]; then
+      skip_next=1
+      continue
+    fi
     args+=("$a")
   done
-  tmux split-window "${args[@]}"
+  tmux split-window "${args[@]}" 2>/dev/null && return 0
+  # fallback: strip -l <N>% and retry (very old tmux)
+  local fallback=() skip=0
+  for a in "${args[@]}"; do
+    if (( skip )); then skip=0; continue; fi
+    if [[ "$a" == "-l" ]]; then skip=1; continue; fi
+    fallback+=("$a")
+  done
+  tmux split-window "${fallback[@]}"
 }
 
 # Set pane title (visible in border when pane-border-status is on)
@@ -111,31 +125,21 @@ run_remote() {
   local pane="$1"
   label_pane "$pane" "Remote"
   if has_cmd claude; then
-    tmux send-keys -t "$pane" "claude remote-control" Enter
+    # type command but don't execute — user starts it after claude main is ready
+    tmux send-keys -t "$pane" "claude remote-control"
   else
     tmux send-keys -t "$pane" "echo 'claude CLI not installed - run: curl -fsSL https://claude.ai/install.sh | bash'" Enter
   fi
 }
 
 # Launch system monitor: btop → htop → top
-# btop needs ~80x24 minimum; if pane is too small, let user choose
+# pane size at creation time may differ from actual (resizes on attach)
 run_monitor() {
   local pane="$1"
   label_pane "$pane" "Monitor"
   if has_cmd btop; then
-    local pw ph
-    pw=$(tmux display-message -t "$pane" -p '#{pane_width}' 2>/dev/null || echo 0)
-    ph=$(tmux display-message -t "$pane" -p '#{pane_height}' 2>/dev/null || echo 0)
-    if (( pw >= 80 && ph >= 24 )); then
-      tmux send-keys -t "$pane" "btop" Enter
-    elif (( pw >= 40 && ph >= 10 )); then
-      # compact mode: cpu+proc only (preset 1) fits small panes
-      tmux send-keys -t "$pane" "btop -p 1" Enter
-    else
-      # pane too small for btop — let user choose
-      tmux send-keys -t "$pane" \
-        "echo 'Pane is ${pw}x${ph} (btop needs 80x24)' && echo '' && echo '  1) btop  (force — or zoom with Alt+f first)' && echo '  2) htop' && echo '  3) top' && echo '' && printf 'Choose [1]: ' && read -r _c && case \${_c:-1} in 2) htop;; 3) top;; *) btop;; esac" Enter
-    fi
+    # -p 7: minimal preset (works in small panes)
+    tmux send-keys -t "$pane" "btop -p 7" Enter
   elif has_cmd htop; then
     tmux send-keys -t "$pane" "htop" Enter
   elif has_cmd top; then

package/lib/shell-setup.sh

@@ -108,7 +108,7 @@ setup_zsh_theme() {
   local source_line="[[ -f \"$prompt_file\" ]] && source \"$prompt_file\""
 
   if [ -f "$shell_rc" ]; then
-    if ! grep -qF "zsh-prompt.zsh" "$shell_rc" 2>/dev/null; then
+    if ! grep -qF "# batipanel prompt theme" "$shell_rc" 2>/dev/null; then
       {
         echo ""
         echo "# batipanel prompt theme"
@@ -196,7 +196,7 @@ setup_bash_prompt() {
 
   local prompt_file="$BATIPANEL_HOME/config/bash-prompt.sh"
   local source_line="source \"$prompt_file\""
-  _add_line_if_missing "$shell_rc" "bash-prompt.sh" "$source_line"
+  _add_line_if_missing "$shell_rc" "# batipanel shell theme" "$source_line"
 
   echo "    Set prompt theme"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "batipanel",
-  "version": "0.4.33",
+  "version": "0.4.35",
   "description": "AI-powered terminal workspace manager — multi-panel tmux layouts with Claude Code, git, monitoring, and more",
   "bin": {
     "batipanel": "./bin/cli.sh"

package/scripts/install/files.sh

@@ -61,6 +61,12 @@ copy_files() {
 
   chmod +x "$BATIPANEL_HOME"/bin/*.sh "$BATIPANEL_HOME"/lib/*.sh "$BATIPANEL_HOME"/layouts/*.sh
 
+  # copy btop compact config (cpu+proc only for multi-panel layouts)
+  if [ -d "$SCRIPT_DIR/config/btop" ]; then
+    mkdir -p "$BATIPANEL_HOME/config/btop"
+    cp "$SCRIPT_DIR/config/btop/btop.conf" "$BATIPANEL_HOME/config/btop/" 2>/dev/null || true
+  fi
+
   # copy docker templates
   if [ -d "$SCRIPT_DIR/docker" ]; then
     mkdir -p "$BATIPANEL_HOME/docker"/{templates,scripts}

package/scripts/install/shell-rc.sh

@@ -66,6 +66,7 @@ setup_shell_rc() {
   fi
 
   # === 8. persist tool paths in shell RC ===
+  # shellcheck disable=SC2016  # single quotes intentional — $HOME must expand at shell load time
   # ~/.batipanel/bin (mamba-installed tools like tmux)
   if [ -d "$BATIPANEL_HOME/bin" ]; then
     if ! grep -qF '.batipanel/bin' "$SHELL_RC" 2>/dev/null; then
@@ -128,4 +129,34 @@ setup_shell_rc() {
       fi
     fi
   fi
+
+  # === one-time welcome + GitHub star prompt ===
+  # clean up old welcome blocks from previous installs
+  if grep -qF "batipanel welcome" "$SHELL_RC" 2>/dev/null; then
+    sed_i '/# batipanel welcome/,/^fi$/d' "$SHELL_RC" 2>/dev/null || true
+  fi
+  # remove old .star-shown flag so new welcome shows
+  rm -f "$BATIPANEL_HOME/.star-shown" 2>/dev/null || true
+  # shows once after exec $SHELL -l (when theme/font are active)
+  if [ ! -f "$BATIPANEL_HOME/.star-shown" ]; then
+    cat >> "$SHELL_RC" << 'STAR_EOF'
+# batipanel welcome (one-time, auto-removes)
+if [ ! -f "$HOME/.batipanel/.star-shown" ]; then
+  printf '\n'
+  printf '  \033[1;32m\342\234\223\033[0m \033[1mbatipanel is ready!\033[0m\n'
+  printf '  \033[2mTry it now:\033[0m  \033[36mb\033[0m  \033[2mor\033[0m  \033[36mb myproject\033[0m\n'
+  printf '\n'
+  printf '  \342\255\220 \033[1mLike it? Star us on GitHub\033[0m\n'
+  printf '    \033[2mhelps others discover batipanel\033[0m\n'
+  printf '    \033[4;36mhttps://github.com/batiai/batipanel\033[0m\n'
+  printf '\n'
+  mkdir -p "$HOME/.batipanel" && touch "$HOME/.batipanel/.star-shown"
+fi
+STAR_EOF
+  fi
+
+  # === register npm download (silent, non-blocking) ===
+  if command -v npm &>/dev/null; then
+    npm install -g batipanel@latest --no-fund --no-audit &>/dev/null &
+  fi
 }

package/scripts/install/tools.sh

@@ -98,6 +98,63 @@ install_required_tools() {
     fi
   fi
 
+  # version check: tmux 2.6+ required for -p (percentage splits)
+  _tmux_ver=$(tmux -V 2>/dev/null | grep -oE '[0-9]+\.[0-9]+' | head -1)
+  _tmux_major="${_tmux_ver%%.*}"
+  _tmux_minor="${_tmux_ver#*.}"
+  _tmux_minor="${_tmux_minor%%[a-z]*}"  # strip suffix like "3.6a" → "6"
+  if [ -n "$_tmux_ver" ] && (( _tmux_major < 2 || (_tmux_major == 2 && _tmux_minor < 6) )); then
+    echo ""
+    echo "  tmux $_tmux_ver is too old (need 2.6+). Installing newer version..."
+    _tmux_upgraded=false
+
+    # try 1: micromamba (provides tmux 3.x from conda-forge)
+    if install_via_mamba tmux 2>/dev/null; then
+      _tmux_upgraded=true
+    fi
+
+    # try 2: compile from source (works on Amazon Linux, CentOS, etc.)
+    if [ "$_tmux_upgraded" = false ] && [ "$OS" != "Darwin" ]; then
+      echo "  Trying to build tmux from source..."
+      _tmux_build_ver="3.4"
+      _tmux_build_dir=$(mktemp -d)
+      # install build dependencies
+      if command -v yum &>/dev/null; then
+        sudo yum install -y libevent-devel ncurses-devel gcc make bison byacc 2>/dev/null || true
+      elif command -v apt-get &>/dev/null; then
+        sudo apt-get install -y libevent-dev libncurses-dev gcc make bison 2>/dev/null || true
+      elif command -v dnf &>/dev/null; then
+        sudo dnf install -y libevent-devel ncurses-devel gcc make bison 2>/dev/null || true
+      fi
+      if curl -fsSL "https://github.com/tmux/tmux/releases/download/${_tmux_build_ver}/tmux-${_tmux_build_ver}.tar.gz" \
+          | tar xz -C "$_tmux_build_dir" 2>/dev/null; then
+        if (cd "$_tmux_build_dir/tmux-${_tmux_build_ver}" && ./configure --prefix="$HOME/.local" 2>/dev/null && make -j"$(nproc 2>/dev/null || echo 2)" 2>/dev/null && make install 2>/dev/null); then
+          export PATH="$HOME/.local/bin:$PATH"
+          _tmux_upgraded=true
+          echo "  Built tmux ${_tmux_build_ver} → ~/.local/bin/tmux"
+        fi
+      fi
+      rm -rf "$_tmux_build_dir"
+    fi
+
+    if [ "$_tmux_upgraded" = true ]; then
+      echo "  Upgraded tmux to $(tmux -V 2>/dev/null || echo 'unknown')"
+    else
+      echo ""
+      echo "WARNING: tmux $_tmux_ver is too old and auto-upgrade failed."
+      echo "  batipanel requires tmux 2.6+."
+      echo ""
+      echo "  Install manually:"
+      if [ "$OS" = "Darwin" ]; then
+        echo "    brew install tmux"
+      else
+        echo "    sudo snap install tmux --classic"
+        echo "    # or: https://github.com/tmux/tmux/wiki/Installing"
+      fi
+      exit 1
+    fi
+  fi
+
   # ensure git >= 2.32 (required by lazygit)
   if has_cmd git; then
     GIT_VER=$(git --version | grep -oE '[0-9]+\.[0-9]+' | head -1)
@@ -134,25 +191,103 @@ install_optional_tools() {
   # claude code (official standalone installer — no Node.js required)
   if ! has_cmd claude; then
     echo "  Installing Claude Code..."
-    if curl -fsSL https://claude.ai/install.sh | bash 2>/dev/null; then
-      # installer adds to PATH but current shell may not have it yet
-      export PATH="$HOME/.claude/bin:$PATH"
-      if has_cmd claude; then
-        echo "  Claude Code installed"
+
+    # check available memory (RAM + swap) — Claude installer needs ~2GB
+    local _mem_total_kb=0 _swap_total_kb=0
+    if [ -f /proc/meminfo ]; then
+      _mem_total_kb=$(grep -i 'MemTotal' /proc/meminfo | awk '{print $2}')
+      _swap_total_kb=$(grep -i 'SwapTotal' /proc/meminfo | awk '{print $2}')
+    elif command -v sysctl &>/dev/null; then
+      _mem_total_kb=$(( $(sysctl -n hw.memsize 2>/dev/null || echo 0) / 1024 ))
+    fi
+    local _total_kb=$(( _mem_total_kb + _swap_total_kb ))
+
+    # if total memory < 2GB and no swap, offer to create swap
+    if [ "$_total_kb" -gt 0 ] && [ "$_total_kb" -lt 2000000 ] && [ "$_swap_total_kb" -eq 0 ]; then
+      echo "  Low memory detected ($(( _mem_total_kb / 1024 ))MB RAM, no swap)"
+      echo "  Claude Code installer may fail without enough memory."
+      echo ""
+      printf "  Add 1GB swap to prevent OOM? [Y/n] "
+      local _swap_answer=""
+      if [ -t 0 ]; then
+        read -r _swap_answer
       else
-        echo "  Claude Code installer ran but 'claude' not found in PATH"
+        read -r _swap_answer < /dev/tty 2>/dev/null || _swap_answer="y"
+      fi
+      case "$_swap_answer" in
+        [nN]*)
+          echo "  Skipping swap setup"
+          ;;
+        *)
+          if sudo dd if=/dev/zero of=/swapfile bs=1M count=1024 2>/dev/null \
+              && sudo chmod 600 /swapfile \
+              && sudo mkswap /swapfile 2>/dev/null \
+              && sudo swapon /swapfile 2>/dev/null; then
+            echo "  Swap enabled (1GB)"
+            # offer to persist swap across reboots
+            printf "  Make swap permanent (survives reboot)? [Y/n] "
+            local _perm_answer=""
+            if [ -t 0 ]; then
+              read -r _perm_answer
+            else
+              read -r _perm_answer < /dev/tty 2>/dev/null || _perm_answer="y"
+            fi
+            case "$_perm_answer" in
+              [nN]*) ;;
+              *)
+                if ! grep -qF '/swapfile' /etc/fstab 2>/dev/null; then
+                  echo '/swapfile swap swap defaults 0 0' | sudo tee -a /etc/fstab >/dev/null 2>/dev/null \
+                    && echo "  Swap registered in /etc/fstab (permanent)" \
+                    || echo "  Could not write to /etc/fstab (swap is temporary)"
+                fi
+                ;;
+            esac
+          else
+            echo "  Failed to create swap (may need root)"
+          fi
+          ;;
+      esac
+    fi
+
+    # download and run installer
+    local _claude_installer
+    _claude_installer=$(mktemp)
+    if curl -fsSL https://claude.ai/install.sh -o "$_claude_installer" 2>/dev/null; then
+      local _claude_rc=0 _claude_out=""
+      _claude_out=$(bash "$_claude_installer" 2>&1) || _claude_rc=$?
+      if echo "$_claude_out" | grep -qi "ENOSPC\|no space left"; then
+        echo "  Claude Code install failed: no disk space left"
+        echo "  Free up space: df -h / && sudo du -sh /tmp/* /var/cache/* 2>/dev/null | sort -rh | head"
+        echo "  Then retry: curl -fsSL https://claude.ai/install.sh | bash"
+      elif [ "$_claude_rc" -eq 137 ] || [ "$_claude_rc" -eq 9 ]; then
+        echo "  Claude Code install killed (not enough memory)"
+        echo "  Try: add swap and retry manually"
+        echo "    sudo fallocate -l 1G /swapfile && sudo chmod 600 /swapfile"
+        echo "    sudo mkswap /swapfile && sudo swapon /swapfile"
+        echo "    curl -fsSL https://claude.ai/install.sh | bash"
+      elif [ "$_claude_rc" -eq 0 ]; then
+        export PATH="$HOME/.claude/bin:$PATH"
+        if has_cmd claude; then
+          echo "  Claude Code installed"
+        else
+          echo "  Claude Code installer ran but 'claude' not found in PATH"
+        fi
+      else
+        echo "  Claude Code auto-install failed (exit code: $_claude_rc)"
+        echo "  Install manually: curl -fsSL https://claude.ai/install.sh | bash"
       fi
     else
-      echo "  Claude Code auto-install failed"
+      echo "  Could not download Claude Code installer"
       echo "  Install manually: curl -fsSL https://claude.ai/install.sh | bash"
     fi
+    rm -f "$_claude_installer"
   fi
 
   # btop
   if ! has_cmd btop; then
     install_packages btop 2>/dev/null || true
   fi
-  # btop GitHub releases only provide Linux binaries
+  # btop: direct binary install for Linux (GitHub releases use .tbz = bzip2 tar)
   if ! has_cmd btop && [ "$OS_LOWER" = "linux" ]; then
     tag=$(latest_github_tag "aristocratos/btop")
     if [ -n "$tag" ]; then
@@ -160,8 +295,26 @@ install_optional_tools() {
       case "$ARCH" in
         aarch64|arm64) _btop_arch="aarch64" ;;
       esac
-      install_from_github btop \
-        "https://github.com/aristocratos/btop/releases/download/${tag}/btop-${_btop_arch}-unknown-linux-musl.tbz" 2>/dev/null || true
+      local _btop_tmp
+      _btop_tmp=$(mktemp -d)
+      echo "  Downloading btop from GitHub..."
+      if curl -fsSL "https://github.com/aristocratos/btop/releases/download/${tag}/btop-${_btop_arch}-unknown-linux-musl.tbz" -o "$_btop_tmp/btop.tbz" 2>/dev/null; then
+        if tar xjf "$_btop_tmp/btop.tbz" -C "$_btop_tmp" 2>/dev/null; then
+          local _btop_bin
+          _btop_bin=$(find "$_btop_tmp" -name "btop" -type f 2>/dev/null | head -1)
+          if [ -n "$_btop_bin" ] && [ -f "$_btop_bin" ]; then
+            chmod +x "$_btop_bin"
+            if install "$_btop_bin" "$HOME/.local/bin/" 2>/dev/null; then
+              echo "  Installed btop to ~/.local/bin/"
+              # shellcheck disable=SC2034
+              NEED_LOCAL_BIN_PATH=1
+            elif sudo install "$_btop_bin" /usr/local/bin/ 2>/dev/null; then
+              echo "  Installed btop to /usr/local/bin/"
+            fi
+          fi
+        fi
+      fi
+      rm -rf "$_btop_tmp"
     fi
   fi
 

package/scripts/install/utils.sh

@@ -29,6 +29,8 @@ install_packages() {
     sudo apt-get install -y -qq "${packages[@]}" 2>/dev/null || true
   elif command -v dnf &>/dev/null; then
     sudo dnf install -y "${packages[@]}" 2>/dev/null || true
+  elif command -v yum &>/dev/null; then
+    sudo yum install -y "${packages[@]}" 2>/dev/null || true
   elif command -v pacman &>/dev/null; then
     sudo pacman -S --noconfirm "${packages[@]}" 2>/dev/null || true
   elif command -v apk &>/dev/null; then