Document project-aware autorun aliases

LOCAL_SETUP.txt

@@ -0,0 +1,92 @@
+# codex_exec local shell setup
+# ============================
+#
+# This file records the local runx/rund setup used on this machine. It is
+# also valid Bash and can be copied directly to $HOME/.bash_aliases.
+#
+# Required files:
+#   runx: $HOME/codex_auto_run.py
+#   rund: $HOME/claude_auto_run.py (not included in this repository)
+#
+# Install and reload:
+#   cp LOCAL_SETUP.txt $HOME/.bash_aliases
+#   source $HOME/.bashrc
+
+unalias runx rund 2>/dev/null || true
+
+_autorun_dir_name() {
+    local rel
+
+    if [[ "$PWD" == "$HOME" ]]; then
+        rel="home"
+    elif [[ "$PWD" == "$HOME/"* ]]; then
+        rel="${PWD#"$HOME"/}"
+    else
+        rel="${PWD#/}"
+    fi
+
+    rel="${rel//\//-}"
+    rel="${rel//[^A-Za-z0-9_-]/-}"
+    while [[ "$rel" == *--* ]]; do
+        rel="${rel//--/-}"
+    done
+    while [[ -n "$rel" && ! "${rel:0:1}" =~ [A-Za-z0-9] ]]; do
+        rel="${rel:1}"
+    done
+    [[ -n "$rel" ]] || rel="home"
+
+    # codex_auto_run.py limits a session prefix to 48 characters.
+    if (( ${#rel} > 45 )); then
+        rel="${rel:0:28}-${rel: -16}"
+    fi
+    printf '%s' "$rel"
+}
+
+runx() {
+    local base
+    base="$(_autorun_dir_name)"
+    python3 "$HOME/codex_auto_run.py" --session-prefix "${base}-x" "$@"
+}
+
+rund() {
+    local base
+    base="$(_autorun_dir_name)"
+    python3 "$HOME/claude_auto_run.py" --session-prefix "${base}-d" "$@"
+}
+
+# Usage:
+#   cd $HOME/code/my_project
+#   runx
+#   rund
+#
+# Start with an initial prompt:
+#   runx -p "Inspect the project, make the requested changes, and run tests."
+#   rund -p "Inspect the project, make the requested changes, and run tests."
+#
+# Enable Codex web search:
+#   runx -p "Research and complete the task." -- --search
+#
+# Because the launchers default to the current directory, -C is unnecessary
+# after cd. Additional arguments are passed through unchanged.
+#
+# Tmux naming for $HOME/code/my_project:
+#   code-my_project-x    Codex / runx
+#   code-my_project-d    Claude / rund
+#
+# The launcher appends a timestamp/PID uniqueness suffix to the actual tmux
+# session name. The -x and -d suffixes deliberately keep the Codex and Claude
+# approval watchers from scanning each other's sessions.
+#
+# Run status or stop commands from the same project directory so the dynamic
+# prefix matches:
+#   runx --status
+#   rund --status
+#   runx --stop-daemon
+#   rund --stop-daemon
+#
+# Optional global Codex skill on this machine:
+#   Path:   $HOME/.codex/skills/codex-autorun
+#   Invoke: $codex-autorun
+#
+# The filesystem skill name uses a hyphen because Codex skill identifiers do
+# not allow underscores; its UI display name is codex_autorun.

README.md

@@ -152,6 +152,13 @@ By default, private watcher state and logs are stored under `~/.runtime/codex-au
 
 Run `./codex_auto_run.py --help` for all tuning and safety options.
 
+## Optional shell aliases
+
+[`LOCAL_SETUP.txt`](LOCAL_SETUP.txt) contains the current `runx`/`rund` Bash
+functions, project-relative tmux naming rules, usage examples, and the local
+`codex-autorun` skill location. The `rund` function expects a separate
+`~/claude_auto_run.py`, which is not included in this repository.
+
 ## Tests
 
 The unit tests exercise approval-screen detection, argument validation, resume command construction, binary probing, `tmux` command construction, and daemon lifecycle safeguards without starting a real Codex session: