Documentation
Install Hanabito, point it at a model, and give it tools of your own.
Install
curl -fsSL https://hanabi.to/install.sh | sh
The installer picks the build for your system (Linux or macOS, x86_64 or arm64), checks its checksum and installs hanabito to ~/.local/bin. Set HANABITO_VERSION=v0.1.0 to install a specific release, or HANABITO_INSTALL_DIR to install somewhere else. To update, run it again. The Linux build is fully static, so it runs on any distribution.
hanabito opens the terminal interface. hanabito --prompt "..." runs headless: answers go to stdout and everything else to stderr, so it drops into scripts. hanabito --help lists the options and key bindings.
Releases, manual downloads and checksums are on GitLab. To uninstall, delete ~/.local/bin/hanabito, the configuration in ~/.hanabito and the saved sessions in ~/.local/share/hanabito.
Configuration
Hanabito reads two .hanabito folders, each of which can hold a hanabito.json and a prelude.js:
~/.hanabito/is global. The first launch creates it, with ahanabito.jsonset up for one OpenAI-compatible server athttp://127.0.0.1:8080/v1, and aprelude.jsthat holds only comments..hanabito/in the directory you launch from is the project layer. Both files there are optional, and you can commit them with the project.
The project's hanabito.json is merged over the global one. Objects merge key by key, so a project can raise limits.max_tokens without restating the providers. Arrays and other values replace, so a project that sets tools replaces the global list.
hanabito --check-config checks the configuration, builds the JavaScript environment and runs the preludes, then exits. Unknown keys are errors, which catches typos. Each file can be up to 64 KiB.
--config FILE skips both folders: that file is the whole configuration, and the only prelude is the prelude.js next to it, if there is one. Saved sessions live in ~/.local/share/hanabito, or $XDG_DATA_HOME/hanabito, or wherever data_dir points.
Providers
Each provider names an endpoint, its API and the environment variable that holds its key. API keys never go in the file. Use "api_key_env": "" for a local server without authentication. api is chat_completions (any OpenAI-compatible server), responses or anthropic_messages.
{
"providers": [
{
"name": "openai",
"api": "responses",
"base_url": "https://api.openai.com/v1",
"api_key_env": "OPENAI_API_KEY",
"models": [
{"id": "your-model", "context_window": 128000, "max_output_tokens": 16384}
]
}
],
"agent_defaults": {"main": {"provider": "openai", "model": "your-model"}},
"limits": {"max_tokens": 128000, "max_output_tokens": 16384}
}
agent_defaults.main picks the model a session starts with, and /model provider model switches it for the next turn. The context and output budgets are the smaller of limits and the model's own figures. The defaults are small (32,768 and 4,096 tokens), so set limits to match your model.
Tools
The model works through one JavaScript tool and the hanabi functions inside it: reading, searching and editing files, and, in relaxed mode, running shell commands. You add tools of your own as fixed commands in tools:
"tools": [
{"name": "build", "command": "make", "effect": "derived",
"description": "Build the project."},
{"name": "test", "command": "make test", "effect": "derived",
"description": "Run the tests."},
{"name": "format", "command": "make format",
"description": "Format the sources in place."}
]
Each one becomes hanabi.build() and so on. The model sees its name and the first line of its description, and gets back the output, exit code and whether it timed out. A fixed command takes no arguments: it always runs exactly the command you wrote, in the workspace, for at most limits.command_timeout_ms (30 seconds by default). You can define up to 16. Names use letters, digits, _ and -. If you define masks, list a tool in a mask's tools for that mask to get it. Without masks, the default mask gets every tool.
What a tool does to your files
Sessions start in strict mode, where Hanabito asks before anything it cannot undo. Each tool says which kind it is, and that decides whether it asks and what /undo does with it:
| Kind | Set with | Asks first | /undo | Examples |
|---|---|---|---|---|
| Irreversible | nothing (the default) | Yes, in strict mode | Can't go back past it | Formatters, make install, deploys, git push |
| Derived | "effect": "derived" | No | Passes over it | Builds, test runs, linters that only report |
| Reversible | "revert": "<tool>" | No | Runs the revert command | Migrations with a rollback, toggling a service |
To choose:
- Does it change your source files, or anything outside the workspace? Leave it irreversible. A formatter is irreversible even though running it twice changes nothing more:
/undowould otherwise leave formatted files behind that it has no record of. - Does it write only output that the sources regenerate, such as build directories, caches and test reports? Mark it derived. After an undo restores the sources, running it again brings the output back in line.
- Can a second command undo it exactly? Make it reversible, but read the next section first.
When unsure, leave a tool irreversible. The worst case is a prompt you didn't need. Relaxed mode (/relax) and --yolo skip the prompts for every kind, but don't change what /undo can do.
Reversible tools
For expert use. Undo is only as correct as the revert command you write, and a revert that fails ends the session, as described below.
revert names another fixed command that undoes this one:
"tools": [
{"name": "migrate", "command": "make migrate", "revert": "rollback",
"description": "Apply pending migrations."},
{"name": "rollback", "command": "make rollback",
"description": "Roll back the last migration."}
]
migrateruns without asking. Before it runs, the session records both commands as they are at that moment, so editing the config later doesn't change what undo runs./undoto a point before it runsmake rollbackin the workspace. It must exit 0 within the command timeout. A non-zero exit, a timeout or a signal fails the undo withRevertCommandFailed.- The model's result from
hanabi.migrate()carries anid, and the model is told thathanabi.revert(result.id)undoes it. That runs the revert as a new action, which can itself be reverted, runningmake migrateagain. The revert tool doesn't need arevertof its own. If the revert command fails,hanabi.revertrejects withRevertCommandFailedand the command's output. The attempt still counts as having run, so a later/undopast it runsmake migrate. revertcan't name the tool itself or a tool that doesn't exist (UnknownRevertTool), and can't be combined with"derived"(DerivedToolWithRevert).
Writing a revert command
- It runs even if the original command failed partway: a command that ran counts as done, whatever its exit code. Make the revert safe to run against a half-finished change, for example by checking state before undoing it.
- It gets nothing from the original run, neither its output nor its arguments. Everything it needs has to be in the command or in the workspace.
- Exit non-zero only when it really couldn't revert. Undo stops on the first failure.
When a revert fails
Undo goes back newest first. When a revert fails, everything newer has already been undone. The failed tool, and everything before it, is left as it was. The session can't continue after that: further prompts and another /undo report SessionUndoIncomplete. Your files stay as they are, so check the state the revert was meant to restore, fix it by hand, and start a new session.
Preludes
~/.hanabito/prelude.js and a project's .hanabito/prelude.js hold JavaScript helpers for the model. Both run, the global one first, when a session starts and after hanabi.reset(). Each top-level function becomes a helper. The model's prompt lists it with its parameters and the // comment line directly above it. A project helper with the same name replaces the global one.
// Matches of a regular expression across the workspace, printed as `path:line: text`.
async function grep(pattern) {
return hanabi.search(".", pattern, { regex: true });
}
A helper can do only what the model could: it acts through hanabi, so each call keeps its own kind. Writes and patches can be undone, a fixed command behaves as its kind says, and hanabi.shell exists only in relaxed mode. To give a helper a command in strict mode, define the command in tools and call hanabi.<name>() from the helper. A prelude can't call hanabi while it loads, only from inside helpers. A prelude that throws stops startup with the error, file and line. All preludes together can be up to 64 KiB.
Undo
Every file edit the model makes is recorded with what it replaced. /undo reverts edits back to a point, newest first, and continues the conversation from there on a new branch. Pass new instructions with it, as in /undo try a smaller change. Undo can't go back past an irreversible action: a shell command, or an irreversible tool. Derived tools don't block it, and reversible tools are undone by running their revert command. The model can also revert a single edit with hanabi.revert(id), as a new change of its own.
Reporting bugs
Open an issue on GitLab. Include hanabito --version, your system, the provider's api and the model, what you did and what happened, and for a crash, everything it printed. Leave out API keys.