Rendered preview

horst

Make Pi aware of current machine and choose different tools or shell guidance per host.

This helps when same Pi setup moves between Linux, macOS, Windows, or machines with different local tooling.

Use it in Pi

Nothing to invoke.

Before each agent turn, Pi receives basic host facts, including OS, hostname, CPU, memory, and login shell.

Optionally declare preferred interactive shell and adjust Pi's active tools for an OS or hostname.

Add this to trusted project .pi/settings.json or user ~/.pi/agent/settings.json:

{
  "horst": {
    "preferredShell": "nu",
    "os": {
      "win32": { "tools": ["+powershell", "-bash"] }
    },
    "hosts": {
      "winbox": { "tools": ["-powershell", "+nu"] }
    }
  }
}

Use lnx, mac, or win32 as OS keys.

Host names match case-insensitively.

Use Pi's +name and -name modifier syntax with exact tool names, not patterns or plain allowlists.

OS modifiers apply first, followed by matching host modifiers in list order. Later modifiers win for the same tool. A project tool array replaces the corresponding user array; an empty array clears that inherited rule.

Use native defaultTools for defaults that do not depend on the OS or hostname. Horst applies its modifiers after Pi's initial tool selection, including command-line selection.

Unknown tool names are ignored with a warning.

Restart Pi after changing settings.

Install through Installation.

Reference

Setting names

Setting
horst

Object fields

Paths below describe fields inside their parent settings object, not literal top-level keys. [] denotes an array element; see setup above for examples and defaults.

Field
horst.os
horst.hosts
horst.preferredShell

<img src="assets/banner.svg" alt="horst" height="70">

# horst

Make Pi aware of current machine and choose different tools or shell guidance per host.

This helps when same Pi setup moves between Linux, macOS, Windows, or machines with different local tooling.

## Use it in Pi

Nothing to invoke.

Before each agent turn, Pi receives basic host facts, including OS, hostname, CPU, memory, and login shell.

Optionally declare preferred interactive shell and adjust Pi's active tools for an OS or hostname.

Add this to trusted project `.pi/settings.json` or user `~/.pi/agent/settings.json`:

```json
{
  "horst": {
    "preferredShell": "nu",
    "os": {
      "win32": { "tools": ["+powershell", "-bash"] }
    },
    "hosts": {
      "winbox": { "tools": ["-powershell", "+nu"] }
    }
  }
}
```

Use `lnx`, `mac`, or `win32` as OS keys.

Host names match case-insensitively.

Use Pi's `+name` and `-name` modifier syntax with exact tool names, not patterns or plain allowlists.

OS modifiers apply first, followed by matching host modifiers in list order.
Later modifiers win for the same tool.
A project tool array replaces the corresponding user array; an empty array clears that inherited rule.

Use native `defaultTools` for defaults that do not depend on the OS or hostname.
Horst applies its modifiers after Pi's initial tool selection, including command-line selection.

Unknown tool names are ignored with a warning.

Restart Pi after changing settings.

Install through [Installation](../../README.md#install).

## Reference

<!-- config:start -->
### Setting names

| Setting |
| --- |
| `horst` |

#### Object fields

Paths below describe fields inside their parent settings object, not literal top-level keys.
`[]` denotes an array element; see setup above for examples and defaults.

| Field |
| --- |
| `horst.os` |
| `horst.hosts` |
| `horst.preferredShell` |
<!-- config:end -->