3 +description: Use when editing or diagnosing Linux user-owned configuration, XDG paths, shell environment, PATH issues, dotfiles, user systemd units, desktop/session config, caches, state dirs, or app config under HOME.
8 +Linux config work inside the user's ownership boundary.
10 +**Boundary:** operate under `$HOME` and user managers only. If a fix needs `/etc`, `/usr`, `/var/lib`, packages, kernel settings, devices, or `sudo`, stop and use `linux` escalation.
14 +1. Identify app/tool, config file discovery rules, and current user/session.
15 +2. Resolve XDG paths; do not hard-code `~/.config` if env overrides exist.
16 +3. Read installed docs: `man`, `--help`, app config docs in repo/package.
17 +4. Inspect current config/env/state.
18 +5. Back up before edits; make minimal change.
19 +6. Validate with app-specific parser/check command.
20 +7. Reload/restart only user-owned process/service. Provide rollback.
24 +| Purpose | Env | Default |
26 +| Config | `XDG_CONFIG_HOME` | `$HOME/.config` |
27 +| Data | `XDG_DATA_HOME` | `$HOME/.local/share` |
28 +| State/logs/history | `XDG_STATE_HOME` | `$HOME/.local/state` |
29 +| Cache | `XDG_CACHE_HOME` | `$HOME/.cache` |
30 +| Runtime sockets | `XDG_RUNTIME_DIR` | set by login/session |
35 +printf 'HOME=%s\nXDG_CONFIG_HOME=%s\nXDG_DATA_HOME=%s\nXDG_STATE_HOME=%s\nXDG_CACHE_HOME=%s\nXDG_RUNTIME_DIR=%s\n' \
36 + "$HOME" "${XDG_CONFIG_HOME:-$HOME/.config}" "${XDG_DATA_HOME:-$HOME/.local/share}" \
37 + "${XDG_STATE_HOME:-$HOME/.local/state}" "${XDG_CACHE_HOME:-$HOME/.cache}" "${XDG_RUNTIME_DIR:-}" 40 +XDG env vars must be absolute paths to be valid.
42 +##
Shell + Environment Diagnosis 44 +The agent's tool shell may not equal the user's interactive shell. Detect before giving syntax:
47 +printf 'SHELL=%s\n' "$SHELL" 48 +getent passwd
"$(id -un)" | awk -F:
'{print "login_shell=" $7}' 49 +printf 'PATH=%s\n' "$PATH" | tr
':' '\n' 52 +Startup files by shell:
54 +| Shell | Common user files | PATH/export syntax |
56 +| bash | `~/.bashrc`, `~/.bash_profile`, `~/.profile` | `export NAME=value` |
57 +| zsh | `~/.zshrc`, `~/.zprofile`, `~/.zshenv` | `export NAME=value` |
58 +| fish | `~/.config/fish/config.fish` | `set -gx NAME value`; `fish_add_path DIR` |
59 +| nushell | `~/.config/nushell/env.nu`, `config.nu` | `$env.NAME = value` |
61 +Prefer editing the shell's config file over emitting complex copy-paste snippets. If root is needed, do not craft fish/nushell sudo heredocs; use `linux` script escalation.
63 +##
User systemd Units 65 +User units live primarily in `$XDG_CONFIG_HOME/systemd/user` (default `~/.config/systemd/user`).
70 +systemctl --user --no-pager --full list-units --failed
71 +systemctl --user --no-pager --full status UNIT
72 +systemctl --user show UNIT -p LoadState -p ActiveState -p SubState -p Result -p ExecMainStatus
73 +systemctl --user cat UNIT
74 +journalctl --user-unit UNIT -b --no-pager --full -n 200
75 +systemd-analyze --user verify
"${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user/UNIT" 78 +After editing a user unit:
81 +systemctl --user daemon-reload
82 +systemctl --user status UNIT --no-pager --full
83 +journalctl --user-unit UNIT -b --no-pager --full -n 100
86 +Restart only if the user asked for restart or the service was active before edit:
89 +systemctl --user restart UNIT
92 +Use `enable --now` only when the user asked for autostart.
98 +backup
="$file.bak.$(date +%Y%m%d-%H%M%S)" 99 +cp -a
"$file" "$backup" 105 +Validation examples:
106 +- systemd user unit: `systemd-analyze --user verify FILE`
107 +- shell config: run the shell parser if available (`bash -n FILE`, `zsh -n FILE`); fish/nushell need shell-specific checks.
108 +- app config: use the app's documented `check`, `validate`, `doctor`, or dry-run command.
114 +| Editing `/etc` from userland task | Stop; use `linux` escalation |
115 +| Assuming bash syntax | Detect shell; prefer editing files or POSIX `sh` scripts |
116 +| Ignoring XDG overrides | Resolve env/defaults first |
117 +| Restarting system service | Only use `systemctl --user`; escalate otherwise |
118 +| Changing config without rollback | Backup + validate + rollback command |