Add resource cleanup and structured data rules to bash style guide

Expand CLAUDE.md with detailed helper function reference,
environment variables section, and commit conventions.
Add .claude/rules/bash-style.md for bash coding standards.

.claude/rules/bash-style.md

@@ -0,0 +1,73 @@
+---
+paths:
+  - "**/*.sh"
+  - "bashrc"
+  - "bin/*"
+---
+
+# Bash Readability Style
+
+The primary goal is code that is **easy to understand at a glance**. Write bash that reads naturally, follows established conventions, and doesn't require the reader to puzzle over clever tricks. Favor clarity and well-known idioms over brevity.
+
+Complements CLAUDE.md. Does not repeat rules already defined there.
+
+## Formatting
+
+- 2-space indentation, no tabs
+- `then`/`do` on same line: `if cond; then` / `for x in list; do`
+- Blank lines between logical sections; no blanks between tightly coupled statements
+- Long pipe chains: one command per line with leading `|`
+
+## Naming
+
+- `UPPER_CASE` — exported env vars and constants; use `readonly` for true constants
+- `snake_case` — local variables and function names
+- `verb_noun` pattern for functions: `set_ps1_prompt`, `docker_aws_login`
+- Meaningful names, no single letters except loop counters (`i`, `f`)
+
+## Functions
+
+```bash
+function do_thing() {
+  local name="$1"
+  local count="${2:-0}"
+  ...
+}
+```
+
+- Always `function name() {` declaration style
+- Always `local` for function variables, assigned on declaration line
+- Name parameters immediately: `local filename="$1"` — no raw `$1` in logic
+- Default values via `${VAR:-default}`
+- Guard clauses with early `return` over deep nesting
+- Keep functions focused — single responsibility
+
+## Syntax Preferences
+
+- `[[ ]]` over `[ ]` for conditionals
+- `(( ))` for arithmetic comparisons
+- `$(command)` for substitution, never backticks
+- Double quotes around expansions: `"$var"`, `"${array[@]}"`
+- Single quotes for literals that must not expand
+- `printf` over `echo` when output contains escapes or format strings
+
+## Resource Cleanup
+
+- Consider `trap cleanup EXIT` with `mktemp` when scripts create temporary files/dirs or acquire resources; skip when it would add unnecessary complexity (short scripts, no temp state)
+
+## Structured Data
+
+- Prefer `jq` for JSON and `yq` for YAML over ad-hoc `grep`/`awk`/string splitting
+- Treat parser errors as fatal; check exit status before using results
+
+## Commands
+
+- Long options for clarity: `--recursive` not `-r` (common test flags `-f`, `-d`, `-e` are fine)
+- Redirect stderr: `> /dev/null 2>&1`
+- `# shellcheck shell=bash` at top of sourced (non-executable) files
+
+## Comments
+
+- Minimal — explain *why*, not *what*
+- URL reference when pattern comes from external source
+- No banner/divider comments

.editorconfig

@@ -7,6 +7,7 @@ insert_final_newline = true
 end_of_line = lf
 indent_size = 4
 indent_style = space
+max_line_length = 120
 
 [*.md]
 trim_trailing_whitespace = false
@@ -14,7 +15,6 @@ indent_size = 2
 
 [*.{java,kt,kts}]
 continuation_indent_size = 4
-max_line_length = 120
 wildcard_import_limit = 99
 
 [*.xml]

CLAUDE.md

@@ -0,0 +1,56 @@
+# Linux Workspace
+
+Dotfiles & workstation automation for Linux, macOS, WSL. `bashrc` loads `rc/*.sh` (ordered by prefix)
+and adds `bin/` to PATH. `$LWS` points to repo root.
+
+## Directory Layout
+
+- `rc/` — Shell init files, loaded in `0X-name.sh` order. Per-tool env setup goes here.
+- `install/` — Idempotent one-off installer scripts (run manually).
+- `bin/` — Scripts auto-added to PATH. New CLI tools go here.
+- `scripts/` — Setup scripts NOT on PATH (git-config, docker fixes, gnome config).
+- `conf/` — Tool configs (vim, WireGuard, WSL).
+- `functions.sh` — Core lib (see below).
+
+## Key Helpers (`functions.sh`)
+
+- `can_run <cmd>` — check if command is available
+- `is_slow_init` / `is_fast_init` — check `LWS_FAST` mode
+- `is_interactive_shell` — true when `[[ $- == *i* ]]`
+- `is_wsl` — detect WSL environment
+- `true_false <val>` — normalize `1/true/yes` to boolean
+- `prepend_path` / `append_path` / `prepend_path_try` / `append_path_try` — safe PATH manipulation
+- `source_try <file>` — source file if it exists
+- `source_directory_sh <dir>` — source all `*.sh` in a directory
+- `xlog <msg>` — debug log (only in interactive + `LWS_DEBUG`)
+
+## Conventions
+
+All new bash scripts should use:
+
+```bash
+#!/usr/bin/env bash
+
+set -E -o errexit -o nounset -o pipefail
+```
+
+Before writing shell code, check `functions.sh` for existing helper functions and prefer them over raw commands.
+
+RC files MUST guard slow tools and check availability:
+
+```bash
+if is_slow_init && can_run pyenv; then
+    # initialize pyenv
+fi
+```
+
+Installers (`install/*.sh`) MUST be idempotent — check before installing.
+
+## Environment Variables
+
+- `LWS_FAST=1` — skips slow tools during shell init
+- `LWS_DEBUG=1` — enables debug logging via `xlog`
+
+## Commits
+
+Do not add `Co-Authored-By` lines to commit messages.

bashrc

@@ -7,13 +7,16 @@ export LWS=$WORKSPACE
 LWS_DEBUG=${LWS_DEBUG:-0}
 LWS_FAST=${LWS_FAST:-0}
 
-echo "Linux Workspace initialization"
+source "$LWS/functions.sh"
 
 if [[ -z $LC_ALL ]]; then
   export LC_ALL=en_US.UTF-8
 fi
 
-source "$LWS/functions.sh"
+if is_interactive_shell; then
+    echo "Linux Workspace initialization"
+fi
+
 source_directory_sh "$LWS/rc"
 source_directory_sh "$HOME/.bashrc.d"
 

bin/upper

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+tr '[:lower:]' '[:upper:]' "$@"
+

bin/xclaude

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+
+# https://code.claude.com/docs/en/settings
+
+import argparse
+import os
+import sys
+import urllib.parse
+
+env = os.environ
+
+
+def die(msg):
+    print(f"Error: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def validate_url(url):
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        die(f"invalid URL scheme '{parsed.scheme}' in --url (expected http or https)")
+
+parser = argparse.ArgumentParser(
+    prog="xclaude",
+    description="Run Claude Code with any OpenAI-compatible API backend.",
+    epilog="""\
+Environment variables (overridable by arguments):
+  CLAUDE_URL    - API base URL (e.g. https://openrouter.ai/api/v1)
+  CLAUDE_TOKEN  - API token/key
+  CLAUDE_MODEL  - model name
+
+If neither URL nor token is set, defaults to Ollama:
+  OLLAMA_HOST   - Ollama server address (default: nvidia.hell), or use --host
+  OLLAMA_MODEL  - Ollama model (default: glm-5:cloud)
+
+Any extra arguments are passed through directly to the claude CLI.
+
+Examples:
+  xclaude
+  xclaude --model qwen3-coder
+  xclaude --url https://openrouter.ai/api/v1 --token sk-XXX --model openai/gpt-4o
+""",
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+)
+parser.add_argument("--url", default=env.get("CLAUDE_URL", ""))
+parser.add_argument("--token", default=env.get("CLAUDE_TOKEN", ""))
+parser.add_argument("--model", default=env.get("CLAUDE_MODEL", ""))
+parser.add_argument("--host", default=env.get("OLLAMA_HOST", "nvidia.hell"))
+args, rest = parser.parse_known_args()
+
+env["DISABLE_TELEMETRY"] = "1"
+
+is_external_api = bool(args.url or args.token)
+if is_external_api:
+    if not args.url:
+        die("no URL specified (--url or CLAUDE_URL)")
+    validate_url(args.url)
+    if not args.token:
+        die("no token specified (--token or CLAUDE_TOKEN)")
+    if not args.model:
+        die("no model specified (--model or CLAUDE_MODEL)")
+    env["ANTHROPIC_BASE_URL"] = args.url
+    env["ANTHROPIC_API_KEY"] = args.token
+    # Remove Ollama auth token if switching to external API
+    env.pop("ANTHROPIC_AUTH_TOKEN", None)
+    model = args.model
+else:
+    host = args.host
+    model = args.model or env.get("OLLAMA_MODEL", "glm-5:cloud")
+    env["ANTHROPIC_BASE_URL"] = f"http://{host}:11434"
+    env["ANTHROPIC_AUTH_TOKEN"] = "ollama"
+    env.pop("ANTHROPIC_API_KEY", None)
+
+cmd = ["claude", "--model", model] + rest
+os.execvp("claude", cmd)

bin/xvim

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+vim "$@" --cmd 'au VimLeave * :!clear'
+clear
+

conf/wsl.conf

@@ -0,0 +1,21 @@
+# https://learn.microsoft.com/en-us/windows/wsl/wsl-config
+
+[boot]
+systemd=false
+
+[user]
+default=lachtan
+
+[automount]
+enabled = true
+
+[network]
+generateHosts = true
+generateResolvConf = false
+
+[interop]
+enabled = false
+appendWindowsPath = false
+
+[gpu]
+enabled = true

fishrc

@@ -0,0 +1,3 @@
+for file in (dirname (status -f))/rc.fish/*.fish
+    source $file
+end

functions.sh

@@ -1,9 +1,14 @@
 # Linux Workspace Functions
+# shellcheck shell=bash
 
 if [ -z "$time_ms" ]; then
     readonly time_ms='date +%s%3N'
 fi
 
+function is_interactive_shell() {
+    [[ $- == *i* ]]
+}
+
 function is_fast_init() {
     (( $LWS_FAST ))
 }
@@ -13,7 +18,7 @@ function is_slow_init() {
 }
 
 function xlog() {
-  if true_false "$LWS_DEBUG"; then
+  if is_interactive_shell && true_false "$LWS_DEBUG"; then
     echo "$@"
   fi
 }
@@ -99,11 +104,11 @@ function source_directory() {
   xlog "LOAD DIR $mask"
   for file in $mask; do
     if [[ -e "$file" ]]; then
-      if (( $LWS_DEBUG )); then
+      if is_interactive_shell && (( $LWS_DEBUG )); then
         start=$($time_ms)
         source "$file"
         stop=$($time_ms)
-        echo "LOAD FILE $file $((stop - start)) ms"
+        xlog "LOAD FILE $file $((stop - start)) ms"
       else
         source "$file"
       fi
@@ -134,3 +139,7 @@ function true_false() {
   # [[ "${1,,}" =~ ^(1|true|yes)$ ]]
   [[ "${1@L}" =~ ^(1|true|yes)$ ]]
 }
+
+function is_wsl() {
+  grep -q -i wsl /proc/version
+}

install.sh

@@ -2,11 +2,29 @@
 
 set -E -o errexit -o nounset -o pipefail
 
-if grep -q -e 'source\s+.*/linux-workspace/bashrc\s*$' $HOME/.bashrc; then
-  echo "Linux Workspace configuration already exists in .bashrc !"
-  exit 1
-else
-  readonly SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" &>/dev/null && pwd -P)
+function install_lws() {
+  local LWS_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" &>/dev/null && pwd -P)
+
+  if grep -q -e "source.*$LWS_DIR/bashrc" $HOME/.bashrc; then
+    echo "SKIP: Linux Workspace configuration already exists in $HOME/.bashrc !"
+  else
     echo "Adding to $HOME/.bashrc"
-  echo "source '$SCRIPT_DIR/bashrc'" >> "$HOME/.bashrc"
-fi
+    echo "source '$LWS_DIR/bashrc'" >> "$HOME/.bashrc"
+  fi
+
+  local FISH_CONF_DIR="$HOME/.config/fish"
+  local FISH_CONF_LWS="$FISH_CONF_DIR/conf.d/lws.fish"
+
+  if [[ -d "$FISH_CONF_DIR" ]]; then
+    if [[ -f "$FISH_CONF_LWS" ]]; then
+      echo "SKIP: Linux Workspace configuration already exists in $FISH_CONF_LWS !"
+    else
+      echo "Adding to $FISH_CONF_LWS"
+      echo "source $LWS_DIR/fishrc" > "$FISH_CONF_LWS"
+    fi
+  else
+    echo "Fish configuration directory not found, skipping fish setup."
+  fi
+}
+
+install_lws

install/claude-code.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+# https://code.claude.com/docs/en/setup
+
+set -E -o errexit -o nounset -o pipefail
+set -x
+
+curl -fsSL https://claude.ai/install.sh | bash
+

install/gemini-cli.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+# https://github.com/google-gemini/gemini-cli
+
+set -E -o errexit -o nounset -o pipefail
+set -x
+
+npm install -g @google/gemini-cli

install/nvm-npm.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# https://github.com/nvm-sh/nvm
+
+set -E -o errexit -o nounset -o pipefail
+set -x
+
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+nvm install node
+nvm use node

rc.fish/01-init.fish

@@ -0,0 +1,5 @@
+set -gx PAGER less
+set -g fish_prompt_pwd_dir_length 0
+
+# set -g fish_autosuggestion_enabled 0
+# fish_config theme choose "fish default"

rc/01-path.sh

@@ -1 +1,2 @@
 prepend_path_try "$HOME/.local/bin"
+prepend_path_try "$HOME/bin"

rc/02-aliases.sh

@@ -1,5 +1,11 @@
 alias nop=':'
 
+# Long format, human-readable, with indicators
+alias ll='ls -lhF'
+# Same as ll but including hidden files
+alias la='ls -lhAF'
+
+
 alias exit-when-error='set -o errexit'
 alias exit-when-unset-variable='set -o nounset'
 alias exit-when-pipe-fail='set -o pipefail'
@@ -9,6 +15,7 @@ alias clws='cd $LWS'
 alias chs=cheatsheet
 
 alias dc=docker-compose
+alias pc=podman-compose
 alias dcl='dcm logs'
 alias dcfilter="sed -r 's/^[^|]+\| //g'"
 

rc/03-values.sh

@@ -0,0 +1,12 @@
+# Terminal colors
+LWS_RED=$(tput setaf 1)
+LWS_GREEN=$(tput setaf 2)
+LWS_CYAN=$(tput setaf 6)
+LWS_COLOR_RESET=$(tput sgr0)
+
+# Bash prompt escape sequences
+LWS_PS1_USER='\u'
+LWS_PS1_HOST='\h'
+LWS_PS1_DIR='\w'
+LWS_PS1_TYPE='\$'
+LWS_PS1_USER_HOST="${LWS_GREEN}${LWS_PS1_USER}@${LWS_PS1_HOST}${LWS_COLOR_RESET}:${LWS_CYAN}${LWS_PS1_DIR}${LWS_COLOR_RESET}"

rc/bash-prompt.sh

@@ -2,19 +2,9 @@
 # https://www.cyberciti.biz/faq/bash-shell-change-the-color-of-my-shell-prompt-under-linux-or-unix/
 # https://linux.101hacks.com/ps1-examples/prompt-color-using-tput/
 
-RED=$(tput setaf 1)
-GREEN=$(tput setaf 2)
-CYAN=$(tput setaf 6)
-COLOR_RESET=$(tput sgr0)
-
 function get_ps1_prompt()
 {
-  local username='\u'
-  local hostname='\h'
-  local workdir='\w'
-  local user_type='\$'
-
-  echo "${debian_chroot:+($debian_chroot)}${GREEN}${username}@${hostname}${COLOR_RESET}:${CYAN}${workdir}${COLOR_RESET}${user_type} "
+  echo "${debian_chroot:+($debian_chroot)}${LWS_PS1_USER_HOST}${LWS_PS1_TYPE} "
 }
 
 function set_ps1_prompt()

rc/cargo.sh

@@ -1,3 +1 @@
-if [[ -f "$HOME/.cargo/env" ]]; then
-  source "$HOME/.cargo/env"
-fi
+source_try "$HOME/.cargo/env"

rc/claude-code.sh

@@ -0,0 +1 @@
+append_path_try $HOME/.local/bin

rc/dircolors.sh

@@ -5,7 +5,7 @@
 #COLORS_FILE="$LWS/conf/dircolors/ansi-light.dircolors"
 COLORS_FILE="$LWS/conf/dircolors/dracula.dircolors"
 
-if [[ -f "$COLORS_FILE" ]]; then
+if can_run dircolors && [[ -f "$COLORS_FILE" ]]; then
     xlog "Loading colors $COLORS_FILE"
     eval "$(dircolors "$COLORS_FILE")"
 else

rc/git-prompt.sh

@@ -9,5 +9,8 @@ GIT_PROMPT_INIT="$GIT_PROMPT_PATH/gitprompt.sh"
 if [ -f "$GIT_PROMPT_INIT" ]; then
   export GIT_PROMPT_PATH
   GIT_PROMPT_ONLY_IN_REPO=1
+  GIT_PROMPT_USER_HOST="${LWS_PS1_USER_HOST}"
+  GIT_PROMPT_START_USER="_LAST_COMMAND_INDICATOR_ ${GIT_PROMPT_USER_HOST}"
+  GIT_PROMPT_START_ROOT="${GIT_PROMPT_START_USER}"
   source "$GIT_PROMPT_INIT"
 fi

rc/go.sh

@@ -0,0 +1 @@
+append_path_try "$HOME/.local/go/bin"

rc/nvm.sh

@@ -0,0 +1,8 @@
+NVM_DIR="$HOME/.nvm"
+if [ -d "$NVM_DIR" ]; then
+  export NVM_DIR
+  [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+  [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
+else
+  unset NVM_DIR
+fi

rc/opencode.sh

@@ -0,0 +1 @@
+append_path_try "$HOME/.opencode/bin"

rc/ssh-agent.sh

@@ -1,9 +1,51 @@
 # Start ssh agent for private key
 
+function _log() {
+  xlog "[ssh-agent] $*"
+}
+
+_SSH_AGENT_NO_KEYS=1
+_SSH_AGENT_NOT_RUNNING=2
+
 for key in id_ecdsa id_rsa; do
   key_filename="$HOME/.ssh/$key"
-  if [ -f $key_filename ]; then
-    eval $(keychain --eval --quiet --agents ssh $key)
+
+  if [ -f "$key_filename" ]; then
+    _log "SSH key: $key_filename"
+
+    if is_wsl; then
+      _log "WSL ON"
+
+      if [ -z "$SSH_AUTH_SOCK" ]; then
+        export SSH_AUTH_SOCK=$HOME/.ssh/ssh-agent.sock
+      fi
+
+      _log "SSH_AUTH_SOCK: $SSH_AUTH_SOCK"
+
+      ssh-add -L &> /dev/null
+      ssh_add_status=$?
+
+      if [[ -S "$SSH_AUTH_SOCK" && $ssh_add_status -eq $_SSH_AGENT_NOT_RUNNING ]]; then
+        _log "SSH agent does not running, delete $SSH_AUTH_SOCK"
+        rm -f "$SSH_AUTH_SOCK"
+      fi
+
+      if [[ ! -S "$SSH_AUTH_SOCK" || $ssh_add_status -eq $_SSH_AGENT_NOT_RUNNING ]]; then
+        _log "Starting ssh-agent"
+        eval "$(ssh-agent -s -a "$SSH_AUTH_SOCK")"
+      fi
+
+      ssh-add -L &> /dev/null
+      ssh_add_status=$?
+
+      if [[ $ssh_add_status -eq $_SSH_AGENT_NO_KEYS ]]; then
+        _log "Adding SSH key to agent"
+        ssh-add "$key_filename"
+      fi
+    else
+      eval "$(keychain --eval --quiet --agents ssh $key)"
+    fi
+
     break
   fi
 done

rc/wsl.sh

@@ -1,10 +0,0 @@
-function is_wsl()
-{
-  grep -q -i wsl /proc/version
-}
-
-if is_wsl; then
-  prepend_path_try "$HOME/.local/bin"
-  append_path_try "$HOME/.arkade/bin"
-  append_path_try "$HOME/.cargo/bin"
-fi