hauntty

Files (1)

• SKILL.md

SKILL.md (first lines)

# hauntty

Use `ht`, the hauntty CLI, to drive persistent terminal sessions from Pi's normal `bash` tool.

hauntty is a terminal session daemon, not a task runner. Prefer terminal primitives: create/attach sessions, send text or keys, wait for screen content, and dump the screen/scrollback.

## When to use

Use hauntty instead of one-shot `bash` when any of these matter:

- shell state should persist across commands (`cwd`, exported env, activated venv/dev shell)
- a server, watcher, REPL, debugger, or TUI should keep running
- the user may need to attach and interact manually, e.g. password prompts
- terminal screen state or scrollback is useful context
- commands should run in a real PTY rather than non-interactive shell

Do not use hauntty for simple non-interactive commands where `bash` is enough.

## Mental model

- A session is a named shell/PTY managed by the hauntty daemon.
- When a session's process ends, hauntty can keep saved terminal state under that session name for later inspection or restore.
- `ht new` creates a session without attaching.
- `ht send` types bytes or keys into an existing session.
- `ht wait` polls the current plain screen until text/regex appears.
- `ht dump` reads the screen, optionally including scrollback.
- `ht attach` is for the human to enter the terminal directly.
- The daemon auto-starts for `attach`, `new`, or `restore`; inspection commands require a running daemon.

## Core commands

```bash
ht new <session> [command ...]              # create/start without attaching
ht attach <session> [command ...]           # attach, creating if needed
ht attach -r <session>                      # read-only attach
ht send <session> '<text>'                  # send literal text, no implicit Enter
ht send <session> --key enter               # send a key
ht send <session> --key ctrl+c              # send modified key
ht wait <session> '<text>'                  # wait for substring on screen
ht wait -e <session> '<regex>'              # wait for regex
ht dump <session>                           # current plain screen
ht dump -S <session>                        # include scrollback
ht dump -J -S <session>                     # include scrollback and join soft wraps
ht list                                     # live sessions
ht list --all                               # live and dead sessions
ht status                                   # daemon/session status
ht kill <session>                           # kill session
ht restore <session>                        # restore saved state and attach
ht new -f <session> [command ...]           # discard saved state for that name and create
ht prune                                    # remove saved state for ended sessions
```

Global options:

```bash
ht --socket <path> ...        # override daemon socket
HAUNTTY_SOCKET=<path> ht ...  # same via env
```

## Sending text and keys

`ht send` does not add a newline. To run a shell command, include a newline in the text or send Enter separately.

Prefer `printf`/ANSI-C quoting for newlines and special characters:

```bash
ht send dev $'npm test\n'
ht send dev 'npm test'
ht send dev --key enter
```

Multiple text arguments are sent in order as separate byte chunks; multiple `--key` flags are sent in order after text chunks.

Key notation is case-insensitive. Supported modifiers:

- `ctrl` / `control`
- `shift`
- `alt` / `opt` / `option`
- `super` / `cmd` / `command`

Supported named keys:

- `enter` / `return`
- `escape` / `esc`
- `tab`, `backspace`, `space`
- arrows: `up`, `down`, `left`, `right`
- `home`, `end`, `pageup` / `pgup`, `pagedown` / `pgdn`
- `insert`, `delete` / `del`
- `f1` through `f12`
- printable single characters, e.g. `a`, `]`, `/`

Examples:

```bash
ht send dev --key ctrl+c
ht send dev --key ctrl+shift+z
ht send dev --key cmd+p
ht send dev --key up --key enter
```

## Waiting and dumping

`ht wait` checks the plain current screen, not full scrollback. Defaults:

- substring match, not regex
- timeout: `30000` ms
- interval: `100` ms
- all rows unless `--row` is set

Examples:

```bash
ht wait dev 'Compiled successfully'
ht wait -t 120000 dev 'ready'
ht wait -e dev 'Tests:.*passed'
ht wait --row 0 dev 'server running'
```

After a wait, inspect output with `dump`:

From seruman/pi-things, MIT.

More from seruman/pi-things