Steward can run commands or open terminals on your machine from a conversation.

## How to use

Type **`/>`** to start **shell mode**, then type your command. Steward chooses **transcript** or **interactive** routing from what you run: most shell commands use transcript (streamed stdout/stderr). Supported programs such as `vim` use an interactive **pseudo-terminal (PTY)** when the **node-pty** native bundle is installed—for example **`/>vim`**.

## Transcript mode

- **What you get:** stdout/stderr are streamed directly into the conversation as plain text. This is **not** a full terminal UI (no curses-style TUI).
- **Setup:** works on **Obsidian desktop** with the CLI bridge enabled. You do **not** need **node-pty** or the prebuilt native bundle for transcript mode.

## Interactive mode

- **What you get:** a terminal-style experience (TTY) in the conversation.
- **When it applies:** the command starts with a supported **interactive program** (for example `vim`, `nvim`, or supported AI CLIs), and the **node-pty** native runtime is available.
- **Setup:** requires the **node-pty** native runtime (prebuilt binaries) and a **local folder vault** so Steward can resolve the bundle path.

## Steward runs shell commands

Besides typing **`/>`** yourself, Steward's AI can also decide to run a shell command as part of answering your request.

- **You always get to approve first.** Before any command runs, Steward shows you what it wants to execute and waits for you to press **Run**. Nothing happens on your machine until you confirm.
- **Skipping confirmation with a whitelist.** If you use a [user-defined command](User-defined-commands.md) and its note includes a `cli.whitelist`, commands that match a whitelist entry will run without asking. A pattern ending with `*` matches any command that starts with that prefix (for example `echo*` matches `echo hello`). This only applies to regular (non-interactive) commands — interactive terminals always ask for confirmation.
- **Output is kept tidy.** After a command finishes, Steward collapses its output into a foldable block so long logs don't clutter your conversation.
- **Interactive terminals.** When a command needs a full terminal (for example `vim` or an AI CLI), Steward will let you know before opening it. Review the message and press **Run** when you're ready.

## What is node-pty, and why is it needed?

**[microsoft/node-pty](https://github.com/microsoft/node-pty)** is a library that allocates a **pseudo-terminal** and runs a process attached to it. Many programs (editors, TUIs, REPLs) assume a TTY: they need cursor control, raw input, and window size updates. A normal pipe (transcript mode) cannot provide that.

Steward therefore uses:

- **Transcript mode** — regular child processes and pipes (no PTY).
- **Interactive mode** — **node-pty** plus a small companion that bridges the PTY to the Obsidian UI.

The **JavaScript** part of node-pty ships with the plugin; **native** `.node` binaries are platform-specific and must match your OS, CPU architecture, and **Node.js ABI** (module version). You can either **build node-pty from source** on your machine (see the [microsoft/node-pty](https://github.com/microsoft/node-pty) build instructions) or **install prebuilt** native addons instead of compiling.

A widely used source of prebuilts is **[homebridge/node-pty-prebuilt-multiarch](https://github.com/homebridge/node-pty-prebuilt-multiarch)**—community-maintained release assets for **multiple platforms** and **Node versions**

**Easiest path:** the plugin writes two installer scripts into your **Steward folder** in the vault. They download a **pinned** tarball from that prebuilt-multiarch project and extract it (by default next to the script, under `node-pty-prebuilt`):

- `install-node-pty-runtime.sh` — macOS, Linux, or Git Bash on Windows
- `install-node-pty-runtime.ps1` — Windows PowerShell

Run the one that matches your environment from your **vault root**. After a successful run, you can use real terminals inside Steward's input and Obsidian's editor.

## Built-in interactive programs

These names are listed out of the box: `vim`, `vi`, `nvim`, `nano`, `gemini`, `claude`, `qwen`, `hermes`.

## Custom interactive programs

In **Steward → Settings → CLI**, use **Interactive programs** to list additional executables, separated by commas or new lines (for example `htop, btop`). Those names are treated like the built-ins for PTY routing.

## Related settings

In the same **CLI** settings section you can also set the **shell executable**, **working directory**, and optional **node-pty native bundle folder** if you did not use the default `Steward/node-pty-prebuilt` layout.