Cross-platform · Bring your own key
A coding agent that asks before it writes.
Hesper is a coding CLI built around a permission gate rather than a sandbox. Every write, every command and every edit has to clear a mode you set — and a brand-new session starts read-only, so nothing touches your repository until you say so.
curl -fsSL https://raw.githubusercontent.com/lzvxck/hesper-code/main/install.sh | bashIntel (x64) and Apple Silicon (arm64).
Three modes. One of them is the default.
Permission isn't a judgment the model makes about itself. Whether a tool can write is derived from a single list in the source tree, and the mode you're in decides what happens next. Cycle it any time with /mode.
read-onlydefaultReads, greps and globs. Cannot write a file or run a command, at all.
approve-eachEvery write and every command stops and asks you first. Nothing runs unanswered.
autoRuns unattended once you've decided the task is worth it. Your call, not the model's.
Built to be predictable.
Gate-first, not sandboxed
The SDK's automatic tool execution is switched off. The loop calls each tool itself, only after the gate has decided it's allowed to run.
Tools are pure functions
read_file, write_file, edit, grep, glob, bash and powershell. Each one is testable on its own, with no model in the loop.
Edits that don't overreach
A three-tier match cascade — exact, line-trimmed, then whitespace-normalized — with a guard against replacing far more than you asked.
Sessions that resume
Every session persists as JSON on disk. --resume picks up the most recent one, or any session by id.
Compaction that stays valid
Past a share of the context window, evicted turns collapse into goal, progress, blockers and next steps — never splitting a tool call from its result.
Your key, your machine
Bring your own API key. It's stored owner-only, written atomically, and read from your environment first. Hosted accounts stay optional.
Then three commands.
- 01
hesper --versionConfirm the binary is on your PATH.
- 02
hesper config set GROQ_API_KEY <your-key>Stored owner-only on your machine. An environment variable wins over it.
- 03
hesper loginOptional — only if you want a hosted account. The BYOK path never needs it.
Supported platforms
One script detects your OS and CPU architecture and downloads the matching binary. Windows gets a real PowerShell, not a translation layer.
| OS | Architectures |
|---|---|
| macOS | Intel (x64), Apple Silicon (arm64) |
| Linux | x64, arm64 |
| Windows | x64 |
Start in read-only. Decide from there.
One command to install, and nothing writes to your repository until you hand it permission.