Hephaestus

Hephaestus, heph at the prompt, is a coding agent that runs in your terminal and never touches your files without showing you first.

You describe a change. A model reads your project, edits a private copy of it, runs your project's own checks, and hands the result back as a set of hunks, each one labeled with the reason the model gave for making it. You accept the hunks you want, reject the ones you do not, say why, and the model tries again with your words in front of it. What you accept remains private to that conversation until /commit; what you reject never publishes.

That is the whole idea, and everything else in this book is a consequence of it:

• The model works in a shadow worktree based on committed upstream plus that conversation's accepted private state. Dirty checkout files are not imported, and reviewed changes publish only with /commit.

• Reads are silent. Edits are visible as they happen but need no approval, because review stands between them and your files. Only commands that reach outside the worktree, a shell command or a fetch from the network, stop to ask, and a prompt says exactly what it is asking and what saying yes will remember.

• Acceptance gates, commands you configure such as cargo test, run on what the model changed before you are asked to look at it. A failing gate goes back to the model, not to you.

• Every turn is recorded: the prompt, the model's words, each tool call with its parameters and result, what it cost. A turn you interrupt, or leave unreviewed, is there when you come back.

Heph talks to Claude models, directly through the Anthropic API or through AWS Bedrock, and to anything that speaks the same protocol.

How to read this book

Getting Started takes you from nothing to a reviewed, applied change in three short chapters. Read it in order.

Using Heph explains each part of a session as you will meet it: the turn, the screen, prompts and permissions, review, gates, models, and how the same engine runs without a screen from a script or a pipe. Read it once through, then come back to chapters as you need them.

Configuration is one chapter per section of the config file, with every key and its default.

Reference is the terse version of everything: every flag, key, slash command, tool, and exit code, and what the model is told about you.

This book describes what heph does today. The design it is built toward is larger; the last page says which parts of that design have not arrived, so you are not left looking for them.