← All case studies

AI Engineering · Generates shell commands and never runs them

herdr-ask

A Rust command assistant for Herdr and any terminal. It turns a plain-English request into a shell command, shows it for review, and inserts it into the pane without pressing Enter, across local Ollama, OpenAI-compatible servers, direct OpenAI and Anthropic APIs, and the Codex, Claude Code, and Pi CLIs.

The Project

I built herdr-ask as a command helper that stops short of the shell. You describe the command you need, the popup shows what it generated, and Ctrl+Enter inserts that text into the pane you came from. Nothing runs until you press Enter yourself. It runs as a popup inside Herdr and as a standalone command in any terminal.

The first stage commit landed on July 17, 2026. v0.1.0 went out on July 20 with binaries for Apple silicon and Intel Macs and for x86_64 and arm64 Linux, plus a SHA256SUMS file. It installs with cargo install, with Homebrew, or with herdr plugin install.

Getting a command without running one

A model’s answer is only text, and text pasted into a shell can do real damage. Several rules keep the person at the keyboard in control:

  • Insertion calls Herdr’s pane send-text and never sends Enter. The pane module rules out pane run and send-keys enter by name.
  • A response with prose or several code blocks is marked suspicious, and the popup requires an explicit “insert anyway” before inserting it.
  • A destructive-pattern check labels commands such as rm -rf and git reset --hard. It only annotates. The source says a missing warning is not a safety guarantee.
  • The Claude adapter passes an empty --allowed-tools list where the installed version supports it, Pi runs with --no-tools, and Codex runs with --sandbox read-only.
  • Claude and Pi receive prompts on stdin, so a request that starts with a dash cannot be parsed as a flag.

Before the release, I checked the riskiest assumption by hand. A multiline command inserted with Ctrl+Enter landed in the shell buffer, and its intermediate lines did not run.

One interface for local, API, and CLI backends

Every backend implements one Backend trait for health checks, model listing, completion, and streaming. The config has four kinds: openai-compatible, openai, anthropic, and process.

openai-compatible covers any server with GET /v1/models and POST /v1/chat/completions, which the source names as Ollama, LM Studio, llama.cpp, vLLM, and LiteLLM. Ollama is the default, at http://127.0.0.1:11434/v1 with no credential, so a fresh install needs no key. The openai kind calls the Responses API, and anthropic calls the Messages API.

process runs a CLI as a fresh, ephemeral invocation in the source pane’s directory. Adapters exist for Codex, Claude Code, and Pi, and a custom process backend takes any other CLI. Before a CLI is used, herdr-ask checks that the installed version supports the no-session flags. If it does not, the backend is marked unavailable instead of quietly persisting a session.

Keys, context, and no telemetry

Direct API keys live in the macOS Keychain or Linux Secret Service. herdr-ask auth set openai reads the key with echo off. Plaintext keys in config.toml are rejected by the types: the credential reference has no variant that holds a value, so a bare string fails to parse. Secrets travel in SecretString containers, and error text is redacted before it is truncated.

Terminal output is attached only when you press Ctrl+O. Conversations stay in memory, and prompt history is off by default. If you turn it on, only prompts are written, to an owner-only file. Ctrl+X exports the current conversation as Markdown into the source directory. The README promises no telemetry, analytics, accounts, or update checker. I searched the source for telemetry and analytics code and found none.

Shipping it as a Herdr plugin

The plugin’s build step runs scripts/install-release-binary.sh. It downloads the release tarball for the machine’s target and the release’s SHA256SUMS, compares SHA-256 hashes, and installs only on a match. It fails closed on an unsupported platform, a missing checksum entry, or a mismatch.

The checksum comes from the same release as the binary, so the check confirms the download matches what was published. It does not establish who built the binary. In Herdr 0.7.x, pane commands resolve through PATH only, so a manifest pointing at bin/herdr-ask could never start. The manifest launches the bundled binary through sh -c and the HERDR_PLUGIN_ROOT variable that Herdr sets for plugins.

Wrap Up

The interesting decisions here are about boundaries. The model can be a local Ollama model, a hosted API, or a CLI you already pay for. The key stays in the keychain, and running a command stays with the person at the keyboard. v0.1.0 is out, and CI runs the test suite on macOS and Linux. The roadmap lists Windows release artifacts and an optional model-list cache as next.