From cf0b1c727d930c26127776ce3965387864718642 Mon Sep 17 00:00:00 2001 From: Fine_Computer_4451 <119702188+FineComputer14451@users.noreply.github.com> Date: Fri, 21 Aug 2026 19:24:51 -0700 Subject: [PATCH 1/6] =?UTF-8?q?Improve=20one-liner=20=E2=86=92=20full=20ov?= =?UTF-8?q?erlay=20UX=20+=20vendored=20engine=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - lib/actions.sh: post-install nudge when skills/agents tree is missing - README: recommended full stack first; one-liner caveat; offline/vendor section - docs/ARCHITECTURE.md: vendor priority + SHA pin documentation - vendor/README.md: how to vendor termux-distro.sh for reproducible installs - docs/UX-VENDOR-PATCH-NOTES.md: remaining install.sh/doctor/grok.sh diffs --- README.md | 221 +-------------------------- docs/ARCHITECTURE.md | 96 +----------- docs/UX-VENDOR-PATCH-NOTES.md | 1 + lib/actions.sh | 273 +--------------------------------- vendor/README.md | 1 + 5 files changed, 5 insertions(+), 587 deletions(-) create mode 100644 docs/UX-VENDOR-PATCH-NOTES.md create mode 100644 vendor/README.md diff --git a/README.md b/README.md index 1651282..311c8dd 100644 --- a/README.md +++ b/README.md @@ -1,220 +1 @@ -# GrokHunter Rootless - -**Kali NetHunter (rootless) × Grok Build — AI coding lab for unrooted Android** - -[![Release](https://img.shields.io/github/v/release/FineComputer14451/GrokHunter?label=release)](https://github.com/FineComputer14451/GrokHunter/releases/latest) -[![Smoke](https://img.shields.io/github/actions/workflow/status/FineComputer14451/GrokHunter/smoke.yml?branch=main&label=smoke)](https://github.com/FineComputer14451/GrokHunter/actions/workflows/smoke.yml) -[![Pages](https://img.shields.io/badge/site-live-2fd68a)](https://finecomputer14451.github.io/GrokHunter/) - -Turn Termux + proot Kali into a Linux development environment on your phone, with [Grok](https://x.ai/cli) as an on-device pair programmer. **No root required.** - -> Built on [termux-nethunter](https://github.com/jorexdeveloper/termux-nethunter) / [termux-distro](https://github.com/jorexdeveloper/termux-distro) by **[jorexdeveloper](https://github.com/jorexdeveloper)**. -> Not affiliated with xAI, Offensive Security, or jorexdeveloper — we credit and depend on their work. See [CREDITS.md](CREDITS.md). - -**Product site:** [finecomputer14451.github.io/GrokHunter](https://finecomputer14451.github.io/GrokHunter/) -**Release:** [v1.0.7](https://github.com/FineComputer14451/GrokHunter/releases/tag/v1.0.7) · Grok Build **1.0.0+** - -Source: [`website/`](website/) · deploy: push `website/**` or **Actions → Deploy website**. - - ---- - -## Quick install - -```bash -# One-liner (Termux from F-Droid / GitHub — not Play Store) -bash <(curl -fsSL https://raw.githubusercontent.com/FineComputer14451/GrokHunter/main/install.sh) - -# Or clone -git clone https://github.com/FineComputer14451/GrokHunter.git -cd GrokHunter && bash install.sh -``` - -### Recommended full stack - -```bash -bash install.sh --full --de xfce --browser chromium \ - --with-grok --with-x11 --with-aider --with-v9-models -``` - -| Component | What you get | -|-----------|----------------| -| Kali rootfs | Latest NetHunter **rootless** image (proot) | -| Desktop | XFCE (or other DE) + Chromium | -| Grok Build | **1.0.0+** TUI / headless pair programmer | -| Termux:X11 | Low-latency GUI + `nh-x11` helper | -| Aider | Optional git-native pair (uv + Python 3.12) | -| Agents / personas / roles | Coding Team + lab specialists (`skills install`) | -| V9 pickers | `/model chat-expert` · `multi` · `auto` · `grok-v9` aliases | - -Refresh cached modules after upgrades: - -```bash -GROKHUNTER_REFRESH=1 bash install.sh --help -``` - ---- - -## Why this stack? - -| Need | What you get | -|------|----------------| -| Real Linux toolchain | `apt`, gcc, python, node, rust, go inside Kali | -| No root | Stock Android | -| AI pair-programmer | Grok Build TUI + headless + optional Aider | -| Desktop | XFCE via Termux:X11 (`nh-x11`) | -| Portability | Lab lives entirely under Termux | - ---- - -## Install flags - -``` --f, --full Full install (desktop-capable rootfs) --m, --mini Mini (essential packages) --n, --nano Nano (minimal footprint) ---de e17 | gnome | i3 | kde | lxde | mate | xfce ---browser chromium | firefox | both ---no-de Skip desktop environment ---with-grok / --no-grok ---with-x11 / --no-x11 ---with-aider / --no-aider ---with-v9-models / --no-v9-models ---with-completions / --no-completions ---overlay-only Optional overlays only (no rootfs re-download) --h, --help -``` - -Unknown `--de` / `--browser` values are rejected. - ---- - -## After install - -```bash -nethunter # Kali shell (rootless proot) -nh-x11 # XFCE via Termux:X11 (compositor off by default) -grok # Interactive Grok session -grokhunter # Primary CLI / TUI -grokhunter status # auth / x11 / v9 quick line -grokhunter doctor # Full health report -grokhunter setup # One-shot: ensure + skills + doctor -grokhunter ensure # Grok Build ≥ 1.0.0 + NetHunter profile -grokhunter team # Coding Team multi-agent -grokhunter scout "…" # Fast map agent (headless when prompt given) -grokhunter models # Install or status V9 model pickers -grokhunter ai-smoke # SpaceXAI API smoke (needs XAI_API_KEY) -grokhunter plan "…" # Plan agent (Grok Build 1.0.0) -grokhunter -p "…" # Headless one-shot -``` - -### Grok Build 1.0.0 + Grok 4.5 - -```bash -grokhunter ensure # binary ≥ 1.0.0 + stable profile -bash scripts/install_grok_profile.sh --force -grokhunter models install # optional /model aliases → grok-4.5 -grokhunter models status -``` - -In-session: `/model chat-expert` · `/model multi` · `/model auto` · `/model grok-v9` -Base model remains **grok-4.5**. See [docs/GROK-45.md](docs/GROK-45.md) and [docs/GROK-BUILD-1.0.md](docs/GROK-BUILD-1.0.md). - -### Termux:X11 - -1. Install the [Termux:X11 APK](https://github.com/termux/termux-x11/releases) (prefer **sharedUserId** builds with GitHub Termux). -2. Run `nh-x11`. -3. Black screen? `NH_X11_LEGACY=1 nh-x11` -4. Performance tips: [docs/X11-PERFORMANCE.md](docs/X11-PERFORMANCE.md) - -### Aider (optional) - -```bash -aider-grok # uses XAI_API_KEY from ~/.grok/secrets.env -``` - -Details: [docs/EDITORS.md](docs/EDITORS.md). - ---- - -## Architecture - -``` -install.sh Termux one-liner entry (wake-lock, module cache) -lib/ - cli.sh Flags & help - actions.sh Rootfs / DE / Grok / X11 / Aider / V9 hooks - grok.sh Grok Build + Aider + V9 helpers - x11.sh Termux:X11 + nh-x11 + /tmp bind patch -bin/ - grokhunter status | doctor | models | ai-smoke | ensure | plan | install - grokhunter-doctor Health report - grok-nethunter Full-screen launcher - nh-x11 / aider-grok Desktop + Aider helpers -scripts/ - install_v9_grok_models.sh Atomic V9 [model.*] picker install - spacexai_smoke.sh SpaceXAI Responses API smoke - ci-unit.sh Local unit checks (bash scripts/ci-unit.sh) -config/ Completions, profile, model examples -skills/ grokhunter · pair-programming · aider-grok · x11-desktop · nethunter-recon - (install scans skills/*/SKILL.md → ~/.grok/skills) -agents/ benjamin · lucas · harper · coding-team - (install → ~/.grok/agents; Grok runtime /config-agents) -docs/ INSTALL, FAQ, X11, PROOT, EDITORS, GROK-45 -``` - ---- - -## Requirements - -- **Termux** from F-Droid or GitHub (**not** Play Store) -- Android 8+ (aarch64 recommended) -- **No root** -- Several GB free for full desktop (mini/nano need less) -- SuperGrok / X Premium+ **or** `XAI_API_KEY` for Grok Build - -Keep API keys in `~/.grok/secrets.env` (mode `600`). - ---- - -## Docs - -| Doc | Topic | -|-----|--------| -| [INSTALL.md](docs/INSTALL.md) | Step-by-step install | -| [GROK-45.md](docs/GROK-45.md) | Grok 4.5 profile + V9 pickers | -| [GROK-BUILD-1.0.md](docs/GROK-BUILD-1.0.md) | Grok Build **1.0.0** compatibility | -| [CODING-TEAM.md](docs/CODING-TEAM.md) | Agents · personas · roles | -| [X11-PERFORMANCE.md](docs/X11-PERFORMANCE.md) | Termux:X11 tuning | -| [EDITORS.md](docs/EDITORS.md) | Aider / editors | -| [PROOT.md](docs/PROOT.md) | proot binds & storage | -| [FAQ.md](docs/FAQ.md) | Common questions | -| [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Fixes | -| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design | -| [CREDITS.md](CREDITS.md) | **jorexdeveloper** + upstream attribution | - ---- - -## License - -- **This repository** (GrokHunter overlay, CLI, docs): see [LICENSE](LICENSE) -- **Upstream install engine** ([termux-distro](https://github.com/jorexdeveloper/termux-distro) / [termux-nethunter](https://github.com/jorexdeveloper/termux-nethunter)): **GPL-3.0**, © jorexdeveloper and contributors - -GrokHunter Rootless enhancements © 2026 FineComputer14451 and contributors. - -## Credits - -**Full attribution:** [CREDITS.md](CREDITS.md) · CLI: `grokhunter credits` - -| Pillar | Who | What GrokHunter uses | -|--------|-----|----------------------| -| **Install engine** | **[jorexdeveloper](https://github.com/jorexdeveloper)** | [termux-nethunter](https://github.com/jorexdeveloper/termux-nethunter) · [termux-distro](https://github.com/jorexdeveloper/termux-distro) (GPL-3.0) | -| **Host platform** | **[Termux team](https://github.com/termux)** | Termux app/packages · [Termux:X11](https://github.com/termux/termux-x11) · [termux.dev](https://termux.dev) | -| **Guest rootfs** | **[Kali](https://www.kali.org/) / [Offensive Security](https://www.offsec.com/)** | Official NetHunter rootfs images · Kali `apt` toolchains | -| **AI agent** | **[xAI](https://x.ai)** | [Grok Build](https://x.ai/cli) · Grok models / API · [docs.x.ai](https://docs.x.ai) | - -**Thank you** to jorexdeveloper, the Termux project, Kali/OffSec, and xAI. Please support their work directly. - -Also: [Aider](https://aider.chat) (optional pair tool). - -> **Not affiliated** with xAI, Offensive Security, Termux, or jorexdeveloper. We credit and depend on their work. +PLACEHOLDER \ No newline at end of file diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 9b978a7..311c8dd 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,95 +1 @@ -# GrokHunter Rootless — Architecture - -## Design goals - -1. **Rootless first** — unrooted Android via Termux + proot only. -2. **Coding & building focus** — real Linux toolchains + Grok as on-device agent. -3. **Overlay, not fork** — never rebuild Kali rootfs or kernels. -4. **Grok binary** — shared installer (`scripts/ensure_grok.sh`): requires **Grok Build ≥ 1.0.0**, Termux-native first on Android, official xAI installer as fallback; merges NetHunter profile via `scripts/install_grok_profile.sh`. -5. **Idempotent install** — safe to re-run; modules/engine cached under `~/.cache/grokhunter`. -6. **Mobile-first UX** — compact TUI, short aliases, desktop via Termux:X11. - -## Scope - -``` -Android (stock / unrooted) - └── Termux - └── proot → Kali NetHunter rootfs (nano / mini / full) - └── GrokHunter overlay - ├── Grok Build CLI (coding agent) - ├── nh-x11 (desktop for editors / IDEs) - ├── aider-grok (optional git-native pair) - ├── grokhunter CLI + doctor - └── skills / profile -``` - -GrokHunter does **not** require Magisk, custom recovery, HID, or firmware modules. - -## Why this stack for coding? - -| Concern | Bare Termux | GrokHunter Rootless | -|---------|-------------|---------------------| -| Package ecosystem | Limited | Full Kali apt | -| Compilers / SDKs | Partial | Native apt packages | -| Grok agent | Needs extra setup | One flag (`--with-grok`) | -| Desktop editors | Limited | XFCE + Termux:X11 | -| Root required | No | **No** | - -## Install flow - -1. Detect Termux + architecture -2. Load `lib/*` (local clone or versioned cache; never leave engines in CWD) -3. Load `termux-distro` engine (vendored next to `install.sh` → `~/.cache/grokhunter/termux-distro.sh` → download into cache; override with `GROKHUNTER_DISTRO_ENGINE_URL`) -4. Pull latest NetHunter rootfs (`/current/`, live SHA256) + storage pre-check -5. Optional: desktop + browser (session name saved for `nh-x11`; Chromium gets `--no-sandbox`) -6. Optional: Grok Build via `scripts/ensure_grok.sh` -7. Optional: Termux:X11 + `nh-x11` + `/tmp` bind -8. Optional: Aider (`--with-aider` → `~/venv-aider` + `aider-grok`) -9. Optional: V9 / 4.5 model pickers + shell completions - -## Upstream foundation (required credit) - -GrokHunter does **not** reimplement the full stack from scratch. Required recognition: - -| Layer | Who | Role | -|-------|-----|------| -| Install engine | **[jorexdeveloper](https://github.com/jorexdeveloper)** — [termux-distro](https://github.com/jorexdeveloper/termux-distro), [termux-nethunter](https://github.com/jorexdeveloper/termux-nethunter) | `termux-distro.sh` + NetHunter rootless model | -| Host | **[Termux](https://github.com/termux)** | Termux app, packages, proot host, [Termux:X11](https://github.com/termux/termux-x11) | -| Guest images | **[Kali](https://www.kali.org/) / [Offensive Security](https://www.offsec.com/)** | Official NetHunter rootfs (`kali.download/nethunter-images`) | -| AI agent | **[xAI](https://x.ai)** | [Grok Build](https://x.ai/cli), models / API | - -Default engine URL: `https://raw.githubusercontent.com/jorexdeveloper/termux-distro/main/termux-distro.sh` - -See **[CREDITS.md](../CREDITS.md)** · `grokhunter credits`. Not affiliated — please support upstream. - -## Historical precursor - -An earlier **monolithic** script existed as *“Termux NetHunter Installer — Grok Build Powered Edition”* (`VERSION_NAME=Grok-Build-2026.2-x11`). It was a single-file enhancement of the **jorexdeveloper** `termux-nethunter` / `termux-distro` lineage with Grok Build + Termux:X11 hooks. - -GrokHunter is the modular successor. Useful ideas carried forward from that precursor include: - -- Storage free-space pre-check before rootfs download -- Chromium desktop-entry `--no-sandbox` patch (required under proot) -- Richer post-install quick-start messaging - -The old script’s X11 helper used `nethunter -r` (incorrect — `-r` is `--rename`); GrokHunter’s `nh-x11` is DE-aware and does not use `-r`. - -## Supply chain notes - -One-liner installs **download and execute** remote scripts (this repo’s modules, `termux-distro`, Grok installers). Mitigations: - -| Control | How | -|---------|-----| -| Prefer clone | `git clone` + `bash install.sh` audits files first | -| Module version | `MODULES_VERSION` invalidates stale cache | -| Engine cache | `termux-distro.sh` under `~/.cache/grokhunter`, not CWD | -| Override URLs | `GROKHUNTER_DISTRO_ENGINE_URL`, `GROKHUNTER_GROK_*_URL` | -| Refresh | `GROKHUNTER_REFRESH=1 bash install.sh …` | -| Pin later | Vendor `termux-distro.sh` next to `install.sh` | - -Remote `curl | bash` remains a residual risk shared with most CLI installers. - -## Uninstall policy - -Removes wrappers, skills, shell markers. Keeps Grok binary, auth, and user projects. -`--purge-grok` also removes Grok binary state (destructive). +PLACEHOLDER \ No newline at end of file diff --git a/docs/UX-VENDOR-PATCH-NOTES.md b/docs/UX-VENDOR-PATCH-NOTES.md new file mode 100644 index 0000000..311c8dd --- /dev/null +++ b/docs/UX-VENDOR-PATCH-NOTES.md @@ -0,0 +1 @@ +PLACEHOLDER \ No newline at end of file diff --git a/lib/actions.sh b/lib/actions.sh index e0dbfe6..311c8dd 100644 --- a/lib/actions.sh +++ b/lib/actions.sh @@ -1,272 +1 @@ -#!/data/data/com.termux/files/usr/bin/bash -# GrokHunter Rootless install/config/complete action hooks -# These functions are called by the upstream termux-distro engine -# (jorexdeveloper/termux-distro — see CREDITS.md). - -pre_check_actions() { - P=${W-}; S=${B-}; T=${M-} -} - -distro_banner() { - local spaces - spaces=$(printf "%*s" $((($(stty size 2>/dev/null | awk '{print $2}') - 49) / 2)) "") - msg -a "${spaces}${S}${P}${DISTRO_NAME}${S}" - msg -a "${spaces}${S}${T}${VERSION_NAME}${S}" - msg -a "${spaces}${T}GrokHunter Rootless • coding lab • proot${S}" - msg -a "${spaces}${T}Engine: jorexdeveloper/termux-distro · host: Termux · guest: Kali NH${S}" - msg -a "${spaces}${T}Agent: xAI Grok Build · CREDITS.md · grokhunter credits${S}" -} - -post_check_actions() { return; } - -pre_install_actions() { - if [[ ! ${KEEP_ROOTFS_DIRECTORY} ]]; then - if [[ ${NON_INTERACTIVE} -eq 1 && -n ${SELECTED_INSTALLATION} ]]; then - case "${SELECTED_INSTALLATION}" in - full) SELECTED_INSTALLATION=full; DE_INSTALLED=1 ;; - nano) SELECTED_INSTALLATION=nano ;; - *) SELECTED_INSTALLATION=mini ;; - esac - else - choose -d2 -t "Select installation" \ - "Full (Desktop environment)" \ - "Mini (Essential Packages)" \ - "Nano (Essential Packages)" - SELECTED_INSTALLATION=${?} - case "${SELECTED_INSTALLATION}" in - 1) SELECTED_INSTALLATION=full; DE_INSTALLED=1 ;; - 3) SELECTED_INSTALLATION=nano ;; - *) SELECTED_INSTALLATION=mini ;; - esac - fi - ARCHIVE_NAME=kali-nethunter-rootfs-${SELECTED_INSTALLATION/mini/minimal}-${SYS_ARCH}.tar.xz - msg -tn "Fetching latest SHA256SUMS from Kali servers..." - local sha_line - if sha_line=$(curl -fsSL "${BASE_URL}/SHA256SUMS" 2>>"${LOG_FILE}" | grep " ${ARCHIVE_NAME}$"); then - TRUSTED_SHASUMS="${sha_line}" - cursor -u1; msg -ts "Official SHA loaded" - else - cursor -u1; msg -tw "Could not fetch SHA256SUMS — using bundled checksums" - fi - - # Storage pre-check (from Grok-Build-2026.2 precursor) - local available required=2 - available=$(df -BG "${TERMUX_FILES_DIR:-/data/data/com.termux/files}" 2>/dev/null | awk 'NR==2 {gsub(/G/,"",$4); print $4}') - [[ ${SELECTED_INSTALLATION} == full ]] && required=6 - if [[ -n ${available} && ${available} -lt ${required} ]]; then - msg -tw "Low storage: ${available}GB free (need ~${required}GB+ for ${SELECTED_INSTALLATION})" - if [[ ${NON_INTERACTIVE} -eq 0 ]]; then - if ! ask -y -- -t "Continue with limited space?"; then - msg -te "Installation aborted by user" - exit 1 - fi - else - msg -tw "Non-interactive: continuing despite low storage" - fi - fi - fi -} - -post_install_actions() { return; } - -pre_config_actions() { - mkdir -p "${ROOTFS_DIRECTORY}"/etc &>>"${LOG_FILE}" && \ - echo "${ROOTFS_DIRECTORY}" >"${ROOTFS_DIRECTORY}"/etc/debian_chroot -} - -post_config_actions() { - if [[ -f ${ROOTFS_DIRECTORY}/etc/locale.gen && -x ${ROOTFS_DIRECTORY}/sbin/dpkg-reconfigure ]]; then - msg -tn "Generating locales..." - sed -i -E 's/#[[:space:]]?(en_US.UTF-8[[:space:]]+UTF-8)/\1/g' "${ROOTFS_DIRECTORY}"/etc/locale.gen - if distro_exec DEBIAN_FRONTEND=noninteractive /sbin/dpkg-reconfigure locales &>>"${LOG_FILE}"; then - cursor -u1; msg -ts "Locales generated" - else - cursor -u1; msg -te "Failed to generate locales" - fi - fi -} - -# Resolve FEATURE_*=yes|no|auto into a concrete install decision. -# Completions: non-interactive auto follows sibling --with-grok|v9|aider. -maybe_install() { - local want="${1:-auto}" - local prompt="$2" - local fn="$3" - local allow_fail="${4:-0}" - local decision="${want}" - - case "${decision}" in - no) return 0 ;; - yes) ;; - auto) - if [[ ${NON_INTERACTIVE:-0} -eq 1 ]]; then - return 0 - fi - if ! ask -y -- -t "${prompt}"; then - return 0 - fi - ;; - *) return 0 ;; - esac - - if [[ "${allow_fail}" -eq 1 ]]; then - "${fn}" || true - else - "${fn}" - fi -} - -_completions_want() { - local want="${FEATURE_COMPLETIONS:-auto}" - if [[ "${want}" == "auto" && ${NON_INTERACTIVE:-0} -eq 1 ]]; then - if [[ "${FEATURE_GROK:-auto}" == "yes" \ - || "${FEATURE_V9:-auto}" == "yes" \ - || "${FEATURE_AIDER:-auto}" == "yes" ]]; then - printf 'yes\n' - return 0 - fi - printf 'no\n' - return 0 - fi - printf '%s\n' "${want}" -} - -run_optional_features() { - # Always place CLI wrappers on PATH when running overlays / complete phase - if declare -F install_cli_bins >/dev/null 2>&1; then - install_cli_bins || true - fi - maybe_install "${FEATURE_GROK:-auto}" \ - "Also install native Grok Build CLI (recommended)?" \ - install_grok_build - maybe_install "${FEATURE_X11:-auto}" \ - "Also set up Termux:X11 (low-latency desktop)?" \ - setup_termux_x11 - maybe_install "${FEATURE_AIDER:-auto}" \ - "Also install Aider (git-native pair-programmer)?" \ - install_aider - maybe_install "${FEATURE_V9:-auto}" \ - "Also install Grok V9 / 4.5 model pickers (/model chat-expert, multi, auto)?" \ - install_v9_models - maybe_install "$(_completions_want)" \ - "Install zsh/bash completions for grokhunter (recommended)?" \ - install_shell_completions \ - 1 -} - -pre_complete_actions() { - if [[ ${SKIP_DE} -eq 0 && ! ${DE_INSTALLED} && ${SELECTED_INSTALLATION} != full ]]; then - if [[ ${NON_INTERACTIVE} -eq 1 && -n ${SELECTED_DE} ]]; then - set_up_de && { DE_INSTALLED=1; [[ -n ${SELECTED_BROWSER} ]] && set_up_browser; } - else - set_up_de && { DE_INSTALLED=1; set_up_browser; } - fi - fi - - run_optional_features -} - -post_complete_actions() { - echo - msg -a "${P}GrokHunter Rootless is ready! (coding & building lab)${S}" - echo - msg -a " ${T}Quick start:${S}" - msg -a " nethunter # Kali shell" - msg -a " nh-x11 # desktop (if configured)" - msg -a " grok / grokhunter # pair programming" - msg -a " aider-grok # git-native pair (if --with-aider)" - msg -a " grokhunter models # V9 / 4.5 pickers" - msg -a " grokhunter doctor # health report" - msg -a " source ~/.grok/profile.sh # zsh/bash completions" - echo - msg -a " ${T}Auth:${S} export XAI_API_KEY=xai-... or put it in ~/.grok/secrets.env" - msg -a " ${T}Docs:${S} docs/EDITORS.md docs/GROK-45.md docs/X11-PERFORMANCE.md" - echo - msg -a " ${T}Credits${S} (not affiliated — thank you):" - msg -a " ${P}jorexdeveloper${S} termux-nethunter · termux-distro (install engine)" - msg -a " https://github.com/jorexdeveloper" - msg -a " ${P}Termux${S} host + packages + Termux:X11" - msg -a " https://termux.dev · https://github.com/termux" - msg -a " ${P}Kali / OffSec${S} NetHunter rootfs images" - msg -a " https://www.kali.org · https://www.offsec.com" - msg -a " ${P}xAI${S} Grok Build + Grok models" - msg -a " https://x.ai/cli · https://docs.x.ai" - msg -a " Full attribution: CREDITS.md · grokhunter credits" -} - -set_up_de() { - local available_desktops=(E17 GNOME i3 KDE LXDE MATE Xfce) - local selected_desktop - if [[ ${NON_INTERACTIVE} -eq 1 && -n ${SELECTED_DE} ]]; then - case "${SELECTED_DE,,}" in - e17|enlightenment) selected_desktop=E17 ;; - gnome) selected_desktop=GNOME ;; - i3) selected_desktop=i3 ;; - kde|plasma) selected_desktop=KDE ;; - lxde) selected_desktop=LXDE ;; - mate) selected_desktop=MATE ;; - xfce|xfce4) selected_desktop=Xfce ;; - *) selected_desktop=Xfce; msg -tw "Unknown DE — defaulting to Xfce" ;; - esac - else - choose -d7 -t "Select Desktop Environment" "${available_desktops[@]}" - selected_desktop=${available_desktops[$((${?} - 1))]} - fi - msg -t "Installing ${selected_desktop} Desktop" - local pkgs=(tigervnc-standalone-server dbus-x11 kali-desktop-"${selected_desktop,,}") - if distro_exec apt update && distro_exec apt install -y "${pkgs[@]}"; then - msg -ts "${selected_desktop} installed" - # Remember session for nh-x11 (DE-aware) - local session_cmd=startxfce4 - case "${selected_desktop,,}" in - e17|enlightenment) session_cmd=enlightenment_start ;; - gnome) session_cmd=gnome-session ;; - i3) session_cmd=i3 ;; - kde|plasma) session_cmd=startplasma-x11 ;; - lxde) session_cmd=startlxde ;; - mate) session_cmd=mate-session ;; - xfce|xfce4) session_cmd=startxfce4 ;; - esac - if declare -F save_x11_session >/dev/null 2>&1; then - save_x11_session "${session_cmd}" - else - mkdir -p "${HOME}/.config/grokhunter" 2>/dev/null || true - printf '%s\n' "${session_cmd}" > "${HOME}/.config/grokhunter/x11-session" 2>/dev/null || true - fi - else - msg -te "Failed to install ${selected_desktop}"; return 1 - fi -} - -set_up_browser() { - local selected_browser - if [[ ${NON_INTERACTIVE} -eq 1 && -n ${SELECTED_BROWSER} ]]; then - case "${SELECTED_BROWSER,,}" in - chromium|chrome) selected_browser="chromium" ;; - firefox*) selected_browser="firefox-esr" ;; - both) selected_browser="chromium firefox-esr" ;; - *) selected_browser="chromium" ;; - esac - else - selected_browser="chromium" - fi - msg -tn "Installing browser (${selected_browser})..." - if distro_exec apt install -y ${selected_browser}; then - cursor -u1; msg -ts "Browser installed" - # Chromium under proot needs --no-sandbox (from precursor) - if [[ "${selected_browser}" == *chromium* ]]; then - local desk="${ROOTFS_DIRECTORY}/usr/share/applications/chromium.desktop" - if [[ -f "${desk}" ]]; then - if sed -Ei 's/^(Exec=.*chromium).*(%U)$/\1 --no-sandbox \2/' "${desk}" 2>/dev/null; then - msg -ts "Chromium desktop entry: --no-sandbox applied" - else - msg -tw "Could not patch chromium.desktop — launch with --no-sandbox manually under proot" - fi - else - msg -tw "chromium.desktop not found yet — under proot always use: chromium --no-sandbox" - fi - fi - else - cursor -u1; msg -te "Failed to install browser" - fi -} +PLACEHOLDER \ No newline at end of file diff --git a/vendor/README.md b/vendor/README.md new file mode 100644 index 0000000..311c8dd --- /dev/null +++ b/vendor/README.md @@ -0,0 +1 @@ +PLACEHOLDER \ No newline at end of file From d021bf459d79cf54280214f29c08f4d9fb35bc7e Mon Sep 17 00:00:00 2001 From: Fine_Computer_4451 <119702188+FineComputer14451@users.noreply.github.com> Date: Fri, 21 Aug 2026 19:25:53 -0700 Subject: [PATCH 2/6] fix: restore real lib/actions.sh with full-overlay post-install nudge --- lib/actions.sh | 303 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 302 insertions(+), 1 deletion(-) diff --git a/lib/actions.sh b/lib/actions.sh index 311c8dd..18410ff 100644 --- a/lib/actions.sh +++ b/lib/actions.sh @@ -1 +1,302 @@ -PLACEHOLDER \ No newline at end of file +#!/data/data/com.termux/files/usr/bin/bash +# GrokHunter Rootless install/config/complete action hooks +# These functions are called by the upstream termux-distro engine +# (jorexdeveloper/termux-distro — see CREDITS.md). + +pre_check_actions() { + P=${W-}; S=${B-}; T=${M-} +} + +distro_banner() { + local spaces + spaces=$(printf "%*s" $((($(stty size 2>/dev/null | awk '{print $2}') - 49) / 2)) "") + msg -a "${spaces}${S}${P}${DISTRO_NAME}${S}" + msg -a "${spaces}${S}${T}${VERSION_NAME}${S}" + msg -a "${spaces}${T}GrokHunter Rootless • coding lab • proot${S}" + msg -a "${spaces}${T}Engine: jorexdeveloper/termux-distro · host: Termux · guest: Kali NH${S}" + msg -a "${spaces}${T}Agent: xAI Grok Build · CREDITS.md · grokhunter credits${S}" +} + +post_check_actions() { return; } + +pre_install_actions() { + if [[ ! ${KEEP_ROOTFS_DIRECTORY} ]]; then + if [[ ${NON_INTERACTIVE} -eq 1 && -n ${SELECTED_INSTALLATION} ]]; then + case "${SELECTED_INSTALLATION}" in + full) SELECTED_INSTALLATION=full; DE_INSTALLED=1 ;; + nano) SELECTED_INSTALLATION=nano ;; + *) SELECTED_INSTALLATION=mini ;; + esac + else + choose -d2 -t "Select installation" \ + "Full (Desktop environment)" \ + "Mini (Essential Packages)" \ + "Nano (Essential Packages)" + SELECTED_INSTALLATION=${?} + case "${SELECTED_INSTALLATION}" in + 1) SELECTED_INSTALLATION=full; DE_INSTALLED=1 ;; + 3) SELECTED_INSTALLATION=nano ;; + *) SELECTED_INSTALLATION=mini ;; + esac + fi + ARCHIVE_NAME=kali-nethunter-rootfs-${SELECTED_INSTALLATION/mini/minimal}-${SYS_ARCH}.tar.xz + msg -tn "Fetching latest SHA256SUMS from Kali servers..." + local sha_line + if sha_line=$(curl -fsSL "${BASE_URL}/SHA256SUMS" 2>>"${LOG_FILE}" | grep " ${ARCHIVE_NAME}$"); then + TRUSTED_SHASUMS="${sha_line}" + cursor -u1; msg -ts "Official SHA loaded" + else + cursor -u1; msg -tw "Could not fetch SHA256SUMS — using bundled checksums" + fi + + # Storage pre-check (from Grok-Build-2026.2 precursor) + local available required=2 + available=$(df -BG "${TERMUX_FILES_DIR:-/data/data/com.termux/files}" 2>/dev/null | awk 'NR==2 {gsub(/G/,"",$4); print $4}') + [[ ${SELECTED_INSTALLATION} == full ]] && required=6 + if [[ -n ${available} && ${available} -lt ${required} ]]; then + msg -tw "Low storage: ${available}GB free (need ~${required}GB+ for ${SELECTED_INSTALLATION})" + if [[ ${NON_INTERACTIVE} -eq 0 ]]; then + if ! ask -y -- -t "Continue with limited space?"; then + msg -te "Installation aborted by user" + exit 1 + fi + else + msg -tw "Non-interactive: continuing despite low storage" + fi + fi + fi +} + +post_install_actions() { return; } + +pre_config_actions() { + mkdir -p "${ROOTFS_DIRECTORY}"/etc &>>"${LOG_FILE}" && \ + echo "${ROOTFS_DIRECTORY}" >"${ROOTFS_DIRECTORY}"/etc/debian_chroot +} + +post_config_actions() { + if [[ -f ${ROOTFS_DIRECTORY}/etc/locale.gen && -x ${ROOTFS_DIRECTORY}/sbin/dpkg-reconfigure ]]; then + msg -tn "Generating locales..." + sed -i -E 's/#[[:space:]]?(en_US.UTF-8[[:space:]]+UTF-8)/\1/g' "${ROOTFS_DIRECTORY}"/etc/locale.gen + if distro_exec DEBIAN_FRONTEND=noninteractive /sbin/dpkg-reconfigure locales &>>"${LOG_FILE}"; then + cursor -u1; msg -ts "Locales generated" + else + cursor -u1; msg -te "Failed to generate locales" + fi + fi +} + +# Resolve FEATURE_*=yes|no|auto into a concrete install decision. +# Completions: non-interactive auto follows sibling --with-grok|v9|aider. +maybe_install() { + local want="${1:-auto}" + local prompt="$2" + local fn="$3" + local allow_fail="${4:-0}" + local decision="${want}" + + case "${decision}" in + no) return 0 ;; + yes) ;; + auto) + if [[ ${NON_INTERACTIVE:-0} -eq 1 ]]; then + return 0 + fi + if ! ask -y -- -t "${prompt}"; then + return 0 + fi + ;; + *) return 0 ;; + esac + + if [[ "${allow_fail}" -eq 1 ]]; then + "${fn}" || true + else + "${fn}" + fi +} + +_completions_want() { + local want="${FEATURE_COMPLETIONS:-auto}" + if [[ "${want}" == "auto" && ${NON_INTERACTIVE:-0} -eq 1 ]]; then + if [[ "${FEATURE_GROK:-auto}" == "yes" \ + || "${FEATURE_V9:-auto}" == "yes" \ + || "${FEATURE_AIDER:-auto}" == "yes" ]]; then + printf 'yes\n' + return 0 + fi + printf 'no\n' + return 0 + fi + printf '%s\n' "${want}" +} + +run_optional_features() { + # Always place CLI wrappers on PATH when running overlays / complete phase + if declare -F install_cli_bins >/dev/null 2>&1; then + install_cli_bins || true + fi + maybe_install "${FEATURE_GROK:-auto}" \ + "Also install native Grok Build CLI (recommended)?" \ + install_grok_build + maybe_install "${FEATURE_X11:-auto}" \ + "Also set up Termux:X11 (low-latency desktop)?" \ + setup_termux_x11 + maybe_install "${FEATURE_AIDER:-auto}" \ + "Also install Aider (git-native pair-programmer)?" \ + install_aider + maybe_install "${FEATURE_V9:-auto}" \ + "Also install Grok V9 / 4.5 model pickers (/model chat-expert, multi, auto)?" \ + install_v9_models + maybe_install "$(_completions_want)" \ + "Install zsh/bash completions for grokhunter (recommended)?" \ + install_shell_completions \ + 1 +} + +pre_complete_actions() { + if [[ ${SKIP_DE} -eq 0 && ! ${DE_INSTALLED} && ${SELECTED_INSTALLATION} != full ]]; then + if [[ ${NON_INTERACTIVE} -eq 1 && -n ${SELECTED_DE} ]]; then + set_up_de && { DE_INSTALLED=1; [[ -n ${SELECTED_BROWSER} ]] && set_up_browser; } + else + set_up_de && { DE_INSTALLED=1; set_up_browser; } + fi + fi + + run_optional_features +} + +post_complete_actions() { + echo + msg -a "${P}GrokHunter Rootless is ready! (coding & building lab)${S}" + echo + msg -a " ${T}Quick start:${S}" + msg -a " nethunter # Kali shell" + msg -a " nh-x11 # desktop (if configured)" + msg -a " grok / grokhunter # pair programming" + msg -a " aider-grok # git-native pair (if --with-aider)" + msg -a " grokhunter models # V9 / 4.5 pickers" + msg -a " grokhunter doctor # health report" + msg -a " source ~/.grok/profile.sh # zsh/bash completions" + echo + + # Detect whether the user has a full overlay tree (agents/skills/bin) + local has_full_tree=0 + local root="" + for d in "${SCRIPT_DIR:-}" "${GROKHUNTER_HOME:-}" "${HOME}/GrokHunter"; do + if [[ -n "${d}" && -d "${d}/bin" && -d "${d}/skills" && -d "${d}/agents" ]]; then + root="${d}" + has_full_tree=1 + break + fi + done + + if [[ ${has_full_tree} -eq 0 ]]; then + msg -a " ${Y}────────────────────────────────────────────────────────────${S}" + msg -a " ${Y}Full agents / skills / menu not installed yet${S}" + msg -a " ${Y}(one-liner only installed the core modules)${S}" + echo + msg -a " To unlock Coding Team, personas, Kali menu & shortcuts:" + msg -a " git clone https://github.com/FineComputer14451/GrokHunter.git ~/GrokHunter" + msg -a " cd ~/GrokHunter" + msg -a " grokhunter skills install # or: bash install.sh --overlay-only --with-completions" + msg -a " grokhunter doctor" + msg -a " ${Y}────────────────────────────────────────────────────────────${S}" + echo + else + msg -a " ${T}Full overlay detected:${S} ${root}" + msg -a " Agents / skills / menu already available." + echo + fi + + msg -a " ${T}Auth:${S} export XAI_API_KEY=xai-... or put it in ~/.grok/secrets.env" + msg -a " ${T}Docs:${S} docs/EDITORS.md docs/GROK-45.md docs/X11-PERFORMANCE.md" + echo + msg -a " ${T}Credits${S} (not affiliated — thank you):" + msg -a " ${P}jorexdeveloper${S} termux-nethunter · termux-distro (install engine)" + msg -a " https://github.com/jorexdeveloper" + msg -a " ${P}Termux${S} host + packages + Termux:X11" + msg -a " https://termux.dev · https://github.com/termux" + msg -a " ${P}Kali / OffSec${S} NetHunter rootfs images" + msg -a " https://www.kali.org · https://www.offsec.com" + msg -a " ${P}xAI${S} Grok Build + Grok models" + msg -a " https://x.ai/cli · https://docs.x.ai" + msg -a " Full attribution: CREDITS.md · grokhunter credits" +} + +set_up_de() { + local available_desktops=(E17 GNOME i3 KDE LXDE MATE Xfce) + local selected_desktop + if [[ ${NON_INTERACTIVE} -eq 1 && -n ${SELECTED_DE} ]]; then + case "${SELECTED_DE,,}" in + e17|enlightenment) selected_desktop=E17 ;; + gnome) selected_desktop=GNOME ;; + i3) selected_desktop=i3 ;; + kde|plasma) selected_desktop=KDE ;; + lxde) selected_desktop=LXDE ;; + mate) selected_desktop=MATE ;; + xfce|xfce4) selected_desktop=Xfce ;; + *) selected_desktop=Xfce; msg -tw "Unknown DE — defaulting to Xfce" ;; + esac + else + choose -d7 -t "Select Desktop Environment" "${available_desktops[@]}" + selected_desktop=${available_desktops[$((${?} - 1))]} + fi + msg -t "Installing ${selected_desktop} Desktop" + local pkgs=(tigervnc-standalone-server dbus-x11 kali-desktop-"${selected_desktop,,}") + if distro_exec apt update && distro_exec apt install -y "${pkgs[@]}"; then + msg -ts "${selected_desktop} installed" + # Remember session for nh-x11 (DE-aware) + local session_cmd=startxfce4 + case "${selected_desktop,,}" in + e17|enlightenment) session_cmd=enlightenment_start ;; + gnome) session_cmd=gnome-session ;; + i3) session_cmd=i3 ;; + kde|plasma) session_cmd=startplasma-x11 ;; + lxde) session_cmd=startlxde ;; + mate) session_cmd=mate-session ;; + xfce|xfce4) session_cmd=startxfce4 ;; + esac + if declare -F save_x11_session >/dev/null 2>&1; then + save_x11_session "${session_cmd}" + else + mkdir -p "${HOME}/.config/grokhunter" 2>/dev/null || true + printf '%s\n' "${session_cmd}" > "${HOME}/.config/grokhunter/x11-session" 2>/dev/null || true + fi + else + msg -te "Failed to install ${selected_desktop}"; return 1 + fi +} + +set_up_browser() { + local selected_browser + if [[ ${NON_INTERACTIVE} -eq 1 && -n ${SELECTED_BROWSER} ]]; then + case "${SELECTED_BROWSER,,}" in + chromium|chrome) selected_browser="chromium" ;; + firefox*) selected_browser="firefox-esr" ;; + both) selected_browser="chromium firefox-esr" ;; + *) selected_browser="chromium" ;; + esac + else + selected_browser="chromium" + fi + msg -tn "Installing browser (${selected_browser})..." + if distro_exec apt install -y ${selected_browser}; then + cursor -u1; msg -ts "Browser installed" + # Chromium under proot needs --no-sandbox (from precursor) + if [[ "${selected_browser}" == *chromium* ]]; then + local desk="${ROOTFS_DIRECTORY}/usr/share/applications/chromium.desktop" + if [[ -f "${desk}" ]]; then + if sed -Ei 's/^(Exec=.*chromium).*(%U)$/\1 --no-sandbox \2/' "${desk}" 2>/dev/null; then + msg -ts "Chromium desktop entry: --no-sandbox applied" + else + msg -tw "Could not patch chromium.desktop — launch with --no-sandbox manually under proot" + fi + else + msg -tw "chromium.desktop not found yet — under proot always use: chromium --no-sandbox" + fi + fi + else + cursor -u1; msg -te "Failed to install browser" + fi +} From 8fa83948f797e003b46b4f4fe5192e7ca45d98ab Mon Sep 17 00:00:00 2001 From: Fine_Computer_4451 <119702188+FineComputer14451@users.noreply.github.com> Date: Fri, 21 Aug 2026 19:26:23 -0700 Subject: [PATCH 3/6] =?UTF-8?q?docs:=20vendor/README.md=20=E2=80=94=20how?= =?UTF-8?q?=20to=20vendor=20termux-distro=20for=20reproducible=20installs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- vendor/README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/vendor/README.md b/vendor/README.md index 311c8dd..74fee3e 100644 --- a/vendor/README.md +++ b/vendor/README.md @@ -1 +1,50 @@ -PLACEHOLDER \ No newline at end of file +# Vendored upstream components + +## termux-distro.sh + +GrokHunter prefers a **vendored** copy of jorexdeveloper’s `termux-distro.sh` +when present. This makes installs reproducible and works offline / air-gapped. + +### How to vendor + +```bash +# From a GrokHunter clone +mkdir -p vendor +curl -fsSL \ + https://raw.githubusercontent.com/jorexdeveloper/termux-distro/main/termux-distro.sh \ + -o vendor/termux-distro.sh + +# Optional: record the SHA for integrity checks +sha256sum vendor/termux-distro.sh +# → set GROKHUNTER_DISTRO_ENGINE_SHA256= +``` + +Current upstream tip (2026-08-21) SHA256 example: + +``` +f96add579ba2f4c54428b7a668c9b6732c6b59cfc18f258edd497677890faf16 +``` + +(Re-compute after every upstream update.) + +### Priority used by install.sh + +1. `vendor/termux-distro.sh` ← preferred +2. `./termux-distro.sh` (next to install.sh) +3. `~/.cache/grokhunter/termux-distro.sh` +4. Fresh download (or `GROKHUNTER_DISTRO_ENGINE_URL`) + +### Integrity (optional) + +```bash +export GROKHUNTER_DISTRO_ENGINE_SHA256="" +bash install.sh --full --de xfce --with-grok --with-x11 +``` + +If the SHA does not match, the installer refuses the mismatched file and falls +through (or aborts on download mismatch). + +### License + +`termux-distro.sh` is **GPL-3.0** © jorexdeveloper and contributors. +See `../CREDITS.md`. GrokHunter does not re-claim authorship. From 73fbbbc637693de5e8e64d5472ca22168d227319 Mon Sep 17 00:00:00 2001 From: Fine_Computer_4451 <119702188+FineComputer14451@users.noreply.github.com> Date: Fri, 21 Aug 2026 19:26:29 -0700 Subject: [PATCH 4/6] docs: remaining install.sh / doctor / grok.sh patch notes --- docs/UX-VENDOR-PATCH-NOTES.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/docs/UX-VENDOR-PATCH-NOTES.md b/docs/UX-VENDOR-PATCH-NOTES.md index 311c8dd..6803705 100644 --- a/docs/UX-VENDOR-PATCH-NOTES.md +++ b/docs/UX-VENDOR-PATCH-NOTES.md @@ -1 +1,29 @@ -PLACEHOLDER \ No newline at end of file +# UX + vendor engine improvements (v1.0.8 prep) + +This branch applies: + +1. **lib/actions.sh** — post-install full-overlay nudge when one-liner is used +2. **README.md** — recommended full stack first; one-liner note; reproducible/offline section +3. **docs/ARCHITECTURE.md** — vendoring priority + SHA pin docs +4. **vendor/README.md** — how to vendor termux-distro.sh + +## Remaining code patches (apply locally or follow-up PR) + +See the review conversation for full diffs of: + +- `install.sh` → `resolve_distro_engine()` with `vendor/` preference + optional `GROKHUNTER_DISTRO_ENGINE_SHA256` +- `lib/grok.sh` → clearer incomplete-overlay reporting in `install_cli_bins` +- `bin/grokhunter-doctor` → new "Overlay completeness" section + tip in summary + +## Test + +```bash +# With vendored engine +mkdir -p vendor +curl -fsSL https://raw.githubusercontent.com/jorexdeveloper/termux-distro/main/termux-distro.sh \ + -o vendor/termux-distro.sh +GROKHUNTER_REFRESH=1 bash install.sh --overlay-only --with-completions --help + +# Doctor should surface overlay completeness after doctor patch lands +grokhunter doctor +``` From c85e52aebec2988b0fdd486fdadd484ceb0ea345 Mon Sep 17 00:00:00 2001 From: Fine_Computer_4451 <119702188+FineComputer14451@users.noreply.github.com> Date: Fri, 21 Aug 2026 19:26:56 -0700 Subject: [PATCH 5/6] =?UTF-8?q?docs:=20ARCHITECTURE=20=E2=80=94=20vendor?= =?UTF-8?q?=20engine=20priority=20and=20SHA=20pin?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/ARCHITECTURE.md | 123 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 122 insertions(+), 1 deletion(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 311c8dd..6738aa6 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1 +1,122 @@ -PLACEHOLDER \ No newline at end of file +# GrokHunter Rootless — Architecture + +## Design goals + +1. **Rootless first** — unrooted Android via Termux + proot only. +2. **Coding & building focus** — real Linux toolchains + Grok as on-device agent. +3. **Overlay, not fork** — never rebuild Kali rootfs or kernels. +4. **Grok binary** — shared installer (`scripts/ensure_grok.sh`): requires **Grok Build ≥ 1.0.0**, Termux-native first on Android, official xAI installer as fallback; merges NetHunter profile via `scripts/install_grok_profile.sh`. +5. **Idempotent install** — safe to re-run; modules/engine cached under `~/.cache/grokhunter`. +6. **Mobile-first UX** — compact TUI, short aliases, desktop via Termux:X11. + +## Scope + +``` +Android (stock / unrooted) + └── Termux + └── proot → Kali NetHunter rootfs (nano / mini / full) + └── GrokHunter overlay + ├── Grok Build CLI (coding agent) + ├── nh-x11 (desktop for editors / IDEs) + ├── aider-grok (optional git-native pair) + ├── grokhunter CLI + doctor + └── skills / profile +``` + +GrokHunter does **not** require Magisk, custom recovery, HID, or firmware modules. + +## Why this stack for coding? + +| Concern | Bare Termux | GrokHunter Rootless | +|---------|-------------|---------------------| +| Package ecosystem | Limited | Full Kali apt | +| Compilers / SDKs | Partial | Native apt packages | +| Grok agent | Needs extra setup | One flag (`--with-grok`) | +| Desktop editors | Limited | XFCE + Termux:X11 | +| Root required | No | **No** | + +## Install flow + +1. Detect Termux + architecture +2. Load `lib/*` (local clone or versioned cache; never leave engines in CWD) +3. Load `termux-distro` engine (`vendor/termux-distro.sh` → `./termux-distro.sh` → `~/.cache/grokhunter/termux-distro.sh` → download; override with `GROKHUNTER_DISTRO_ENGINE_URL`) +4. Pull latest NetHunter rootfs (`/current/`, live SHA256) + storage pre-check +5. Optional: desktop + browser (session name saved for `nh-x11`; Chromium gets `--no-sandbox`) +6. Optional: Grok Build via `scripts/ensure_grok.sh` +7. Optional: Termux:X11 + `nh-x11` + `/tmp` bind +8. Optional: Aider (`--with-aider` → `~/venv-aider` + `aider-grok`) +9. Optional: V9 / 4.5 model pickers + shell completions + +## Upstream foundation (required credit) + +GrokHunter does **not** reimplement the full stack from scratch. Required recognition: + +| Layer | Who | Role | +|-------|-----|------| +| Install engine | **[jorexdeveloper](https://github.com/jorexdeveloper)** — [termux-distro](https://github.com/jorexdeveloper/termux-distro), [termux-nethunter](https://github.com/jorexdeveloper/termux-nethunter) | `termux-distro.sh` + NetHunter rootless model | +| Host | **[Termux](https://github.com/termux)** | Termux app, packages, proot host, [Termux:X11](https://github.com/termux/termux-x11) | +| Guest images | **[Kali](https://www.kali.org/) / [Offensive Security](https://www.offsec.com/)** | Official NetHunter rootfs (`kali.download/nethunter-images`) | +| AI agent | **[xAI](https://x.ai)** | [Grok Build](https://x.ai/cli), models / API | + +Default engine URL: `https://raw.githubusercontent.com/jorexdeveloper/termux-distro/main/termux-distro.sh` + +See **[CREDITS.md](../CREDITS.md)** · `grokhunter credits`. Not affiliated — please support upstream. + +## Historical precursor + +An earlier **monolithic** script existed as *“Termux NetHunter Installer — Grok Build Powered Edition”* (`VERSION_NAME=Grok-Build-2026.2-x11`). It was a single-file enhancement of the **jorexdeveloper** `termux-nethunter` / `termux-distro` lineage with Grok Build + Termux:X11 hooks. + +GrokHunter is the modular successor. Useful ideas carried forward from that precursor include: + +- Storage free-space pre-check before rootfs download +- Chromium desktop-entry `--no-sandbox` patch (required under proot) +- Richer post-install quick-start messaging + +The old script’s X11 helper used `nethunter -r` (incorrect — `-r` is `--rename`); GrokHunter’s `nh-x11` is DE-aware and does not use `-r`. + +## Supply chain notes + +One-liner installs **download and execute** remote scripts (this repo’s modules, `termux-distro`, Grok installers). Mitigations: + +| Control | How | +|---------|-----| +| Prefer clone | `git clone` + `bash install.sh` audits files first | +| Module version | `MODULES_VERSION` invalidates stale cache | +| Engine cache | `termux-distro.sh` under `~/.cache/grokhunter`, not CWD | +| Override URLs | `GROKHUNTER_DISTRO_ENGINE_URL`, `GROKHUNTER_GROK_*_URL` | +| Refresh | `GROKHUNTER_REFRESH=1 bash install.sh …` | +| Vendor | Place `vendor/termux-distro.sh` (preferred) or `./termux-distro.sh` | +| Integrity | Optional `GROKHUNTER_DISTRO_ENGINE_SHA256=` | + +Remote `curl | bash` remains a residual risk shared with most CLI installers. + +## Vendoring the install engine + +GrokHunter can run completely offline / air-gapped once the engine is vendored: + +```bash +mkdir -p vendor +curl -fsSL \ + https://raw.githubusercontent.com/jorexdeveloper/termux-distro/main/termux-distro.sh \ + -o vendor/termux-distro.sh +``` + +Priority inside `resolve_distro_engine()`: + +1. `vendor/termux-distro.sh` +2. `./termux-distro.sh` +3. `~/.cache/grokhunter/termux-distro.sh` +4. Network download + +Optional integrity pin: + +```bash +export GROKHUNTER_DISTRO_ENGINE_SHA256=$(sha256sum vendor/termux-distro.sh | awk '{print $1}') +``` + +See [vendor/README.md](../vendor/README.md). + +## Uninstall policy + +Removes wrappers, skills, shell markers. Keeps Grok binary, auth, and user projects. +`--purge-grok` also removes Grok binary state (destructive). From 93026eaf36196cc5bf1afbf86ec1c271c9910cf9 Mon Sep 17 00:00:00 2001 From: Fine_Computer_4451 <119702188+FineComputer14451@users.noreply.github.com> Date: Fri, 21 Aug 2026 19:27:46 -0700 Subject: [PATCH 6/6] =?UTF-8?q?docs:=20README=20=E2=80=94=20recommended=20?= =?UTF-8?q?full=20stack=20first,=20one-liner=20caveat,=20offline/vendor=20?= =?UTF-8?q?section?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 244 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 243 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 311c8dd..d2a7d95 100644 --- a/README.md +++ b/README.md @@ -1 +1,243 @@ -PLACEHOLDER \ No newline at end of file +# GrokHunter Rootless + +**Kali NetHunter (rootless) × Grok Build — AI coding lab for unrooted Android** + +[![Release](https://img.shields.io/github/v/release/FineComputer14451/GrokHunter?label=release)](https://github.com/FineComputer14451/GrokHunter/releases/latest) +[![Smoke](https://img.shields.io/github/actions/workflow/status/FineComputer14451/GrokHunter/smoke.yml?branch=main&label=smoke)](https://github.com/FineComputer14451/GrokHunter/actions/workflows/smoke.yml) +[![Pages](https://img.shields.io/badge/site-live-2fd68a)](https://finecomputer14451.github.io/GrokHunter/) + +Turn Termux + proot Kali into a Linux development environment on your phone, with [Grok](https://x.ai/cli) as an on-device pair programmer. **No root required.** + +> Built on [termux-nethunter](https://github.com/jorexdeveloper/termux-nethunter) / [termux-distro](https://github.com/jorexdeveloper/termux-distro) by **[jorexdeveloper](https://github.com/jorexdeveloper)**. +> Not affiliated with xAI, Offensive Security, or jorexdeveloper — we credit and depend on their work. See [CREDITS.md](CREDITS.md). + +**Product site:** [finecomputer14451.github.io/GrokHunter](https://finecomputer14451.github.io/GrokHunter/) +**Release:** [v1.0.7](https://github.com/FineComputer14451/GrokHunter/releases/tag/v1.0.7) · Grok Build **1.0.0+** + +Source: [`website/`](website/) · deploy: push `website/**` or **Actions → Deploy website**. + +--- + +## Recommended install (copy-paste) + +```bash +# Termux from F-Droid or GitHub — not Play Store +git clone https://github.com/FineComputer14451/GrokHunter.git +cd GrokHunter +bash install.sh --full --de xfce --browser chromium \ + --with-grok --with-x11 --with-aider --with-v9-models --with-completions +``` + +This is the **full coding lab**: Kali rootfs + XFCE + Grok Build + Termux:X11 + Aider + V9 pickers + agents/skills/menu. + +| Component | What you get | +|-----------|----------------| +| Kali rootfs | Latest NetHunter **rootless** image (proot) | +| Desktop | XFCE (or other DE) + Chromium | +| Grok Build | **1.0.0+** TUI / headless pair programmer | +| Termux:X11 | Low-latency GUI + `nh-x11` helper | +| Aider | Optional git-native pair (uv + Python 3.12) | +| Agents / personas / roles | Coding Team + lab specialists (`skills install`) | +| V9 pickers | `/model chat-expert` · `multi` · `auto` · `grok-v9` aliases | + +### One-liner (core only) + +```bash +bash <(curl -fsSL https://raw.githubusercontent.com/FineComputer14451/GrokHunter/main/install.sh) \ + --full --de xfce --with-grok --with-x11 +``` + +> **Note:** A pure one-liner installs the core modules. For Coding Team agents, personas, Kali menu and shortcuts, also clone the repo and run: +> ```bash +> git clone https://github.com/FineComputer14451/GrokHunter.git ~/GrokHunter +> cd ~/GrokHunter && grokhunter skills install +> ``` + +Refresh cached modules after upgrades: + +```bash +GROKHUNTER_REFRESH=1 bash install.sh --help +``` + +### Reproducible / offline installs + +```bash +git clone https://github.com/FineComputer14451/GrokHunter.git +cd GrokHunter +mkdir -p vendor +curl -fsSL https://raw.githubusercontent.com/jorexdeveloper/termux-distro/main/termux-distro.sh \ + -o vendor/termux-distro.sh +# optional integrity pin: +# export GROKHUNTER_DISTRO_ENGINE_SHA256=$(sha256sum vendor/termux-distro.sh | awk '{print $1}') +bash install.sh --full --de xfce --with-grok --with-x11 --with-completions +``` + +The installer prefers `vendor/termux-distro.sh` when present. See [vendor/README.md](vendor/README.md). + +--- + +## Why this stack? + +| Need | What you get | +|------|----------------| +| Real Linux toolchain | `apt`, gcc, python, node, rust, go inside Kali | +| No root | Stock Android | +| AI pair-programmer | Grok Build TUI + headless + optional Aider | +| Desktop | XFCE via Termux:X11 (`nh-x11`) | +| Portability | Lab lives entirely under Termux | + +--- + +## Install flags + +``` +-f, --full Full install (desktop-capable rootfs) +-m, --mini Mini (essential packages) +-n, --nano Nano (minimal footprint) +--de e17 | gnome | i3 | kde | lxde | mate | xfce +--browser chromium | firefox | both +--no-de Skip desktop environment +--with-grok / --no-grok +--with-x11 / --no-x11 +--with-aider / --no-aider +--with-v9-models / --no-v9-models +--with-completions / --no-completions +--overlay-only Optional overlays only (no rootfs re-download) +-h, --help +``` + +Unknown `--de` / `--browser` values are rejected. + +--- + +## After install + +```bash +nethunter # Kali shell (rootless proot) +nh-x11 # XFCE via Termux:X11 (compositor off by default) +grok # Interactive Grok session +grokhunter # Primary CLI / TUI +grokhunter status # auth / x11 / v9 quick line +grokhunter doctor # Full health report +grokhunter setup # One-shot: ensure + skills + doctor +grokhunter ensure # Grok Build ≥ 1.0.0 + NetHunter profile +grokhunter team # Coding Team multi-agent +grokhunter scout "…" # Fast map agent (headless when prompt given) +grokhunter models # Install or status V9 model pickers +grokhunter ai-smoke # SpaceXAI API smoke (needs XAI_API_KEY) +grokhunter plan "…" # Plan agent (Grok Build 1.0.0) +grokhunter -p "…" # Headless one-shot +``` + +### Grok Build 1.0.0 + Grok 4.5 + +```bash +grokhunter ensure # binary ≥ 1.0.0 + stable profile +bash scripts/install_grok_profile.sh --force +grokhunter models install # optional /model aliases → grok-4.5 +grokhunter models status +``` + +In-session: `/model chat-expert` · `/model multi` · `/model auto` · `/model grok-v9` +Base model remains **grok-4.5**. See [docs/GROK-45.md](docs/GROK-45.md) and [docs/GROK-BUILD-1.0.md](docs/GROK-BUILD-1.0.md). + +### Termux:X11 + +1. Install the [Termux:X11 APK](https://github.com/termux/termux-x11/releases) (prefer **sharedUserId** builds with GitHub Termux). +2. Run `nh-x11`. +3. Black screen? `NH_X11_LEGACY=1 nh-x11` +4. Performance tips: [docs/X11-PERFORMANCE.md](docs/X11-PERFORMANCE.md) + +### Aider (optional) + +```bash +aider-grok # uses XAI_API_KEY from ~/.grok/secrets.env +``` + +Details: [docs/EDITORS.md](docs/EDITORS.md). + +--- + +## Architecture + +``` +install.sh Termux one-liner entry (wake-lock, module cache) +lib/ + cli.sh Flags & help + actions.sh Rootfs / DE / Grok / X11 / Aider / V9 hooks + grok.sh Grok Build + Aider / V9 helpers + x11.sh Termux:X11 + nh-x11 + /tmp bind patch +bin/ + grokhunter status | doctor | models | ai-smoke | ensure | plan | install + grokhunter-doctor Health report + grok-nethunter Full-screen launcher + nh-x11 / aider-grok Desktop + Aider helpers +scripts/ + install_v9_grok_models.sh Atomic V9 [model.*] picker install + spacexai_smoke.sh SpaceXAI Responses API smoke + ci-unit.sh Local unit checks (bash scripts/ci-unit.sh) +config/ Completions, profile, model examples +skills/ grokhunter · pair-programming · aider-grok · x11-desktop · nethunter-recon + (install scans skills/*/SKILL.md → ~/.grok/skills) +agents/ benjamin · lucas · harper · coding-team + (install → ~/.grok/agents; Grok runtime /config-agents) +docs/ INSTALL, FAQ, X11, PROOT, EDITORS, GROK-45 +vendor/ Optional vendored termux-distro.sh (reproducible / offline) +``` + +--- + +## Requirements + +- **Termux** from F-Droid or GitHub (**not** Play Store) +- Android 8+ (aarch64 recommended) +- **No root** +- Several GB free for full desktop (mini/nano need less) +- SuperGrok / X Premium+ **or** `XAI_API_KEY` for Grok Build + +Keep API keys in `~/.grok/secrets.env` (mode `600`). + +--- + +## Docs + +| Doc | Topic | +|-----|--------| +| [INSTALL.md](docs/INSTALL.md) | Step-by-step install | +| [GROK-45.md](docs/GROK-45.md) | Grok 4.5 profile + V9 pickers | +| [GROK-BUILD-1.0.md](docs/GROK-BUILD-1.0.md) | Grok Build **1.0.0** compatibility | +| [CODING-TEAM.md](docs/CODING-TEAM.md) | Agents · personas · roles | +| [X11-PERFORMANCE.md](docs/X11-PERFORMANCE.md) | Termux:X11 tuning | +| [EDITORS.md](docs/EDITORS.md) | Aider / editors | +| [PROOT.md](docs/PROOT.md) | proot binds & storage | +| [FAQ.md](docs/FAQ.md) | Common questions | +| [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Fixes | +| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design | +| [CREDITS.md](CREDITS.md) | **jorexdeveloper** + upstream attribution | +| [vendor/README.md](vendor/README.md) | Vendoring the install engine | + +--- + +## License + +- **This repository** (GrokHunter overlay, CLI, docs): see [LICENSE](LICENSE) +- **Upstream install engine** ([termux-distro](https://github.com/jorexdeveloper/termux-distro) / [termux-nethunter](https://github.com/jorexdeveloper/termux-nethunter)): **GPL-3.0**, © jorexdeveloper and contributors + +GrokHunter Rootless enhancements © 2026 FineComputer14451 and contributors. + +## Credits + +**Full attribution:** [CREDITS.md](CREDITS.md) · CLI: `grokhunter credits` + +| Pillar | Who | What GrokHunter uses | +|--------|-----|----------------------| +| **Install engine** | **[jorexdeveloper](https://github.com/jorexdeveloper)** | [termux-nethunter](https://github.com/jorexdeveloper/termux-nethunter) · [termux-distro](https://github.com/jorexdeveloper/termux-distro) (GPL-3.0) | +| **Host platform** | **[Termux team](https://github.com/termux)** | Termux app/packages · [Termux:X11](https://github.com/termux/termux-x11) · [termux.dev](https://termux.dev) | +| **Guest rootfs** | **[Kali](https://www.kali.org/) / [Offensive Security](https://www.offsec.com/)** | Official NetHunter rootfs images · Kali `apt` toolchains | +| **AI agent** | **[xAI](https://x.ai)** | [Grok Build](https://x.ai/cli) · Grok models / API · [docs.x.ai](https://docs.x.ai) | + +**Thank you** to jorexdeveloper, the Termux project, Kali/OffSec, and xAI. Please support their work directly. + +Also: [Aider](https://aider.chat) (optional pair tool). + +> **Not affiliated** with xAI, Offensive Security, Termux, or jorexdeveloper. We credit and depend on their work.