GSHX

GShellHex — terminal autopilot. Summon with gshx.

Gengar drives a live shell: types commands, watches output, answers prompts, takes steers mid-flight, and remembers the room.

npm install -g gshellhex
gshx setup
gshx show me system stats

Requirements

• Node 20+
• A real terminal (Ghostty recommended)
• fish preferred (zsh/bash work)
• DEEPSEEK_API_KEY

Install

npm install -g gshellhex
gshx setup

setup checks deps, wires your shell, and stores your API key.
Postinstall also auto-adds PATH + shell integration (fish / zsh / bash).

gshx doctor                 # health check
gshx deps --install         # install missing tools (fish, chafa, …)
gshx install                # re-wire shell + deps

CI / non-interactive installs: set GSHX_SKIP_POSTINSTALL=1.

Usage

gshx show me system stats
gshx please update homebrew apps
gshx print this directory as a tree
gshx recall brew            # room memory

Steer while it runs: type + Enter · stop aborts · Ctrl-C → shell · Ctrl-C twice → quit gshx.

ghex remains as a legacy alias.

How it works

| Layer | Role | | --- | --- | | Surface | Bottom status bar only — never poisons scrollback | | Pilot | Live PTY — tabs, arrows, confirms, long-job watch | | Mind | LLM loop with efficiency plans, installs, parallel jobs | | Memory | Per-room ledger; survives between summons | | Scribe | Logs your commands while gshx sleeps (fish) |

Surface → Pilot (PTY) → Mind (LLM)
              ↓
           Memory

State lives under ~/.cache/gshx/. Config under ~/.config/gshx/.
Older ~/.cache/ghex data is migrated automatically.

License

MIT · GShadow / Fincher Labs · Ember Glass
Green dashboards lie. I check the bodies.