Setup (hh init)
hh init sets Halfhand up explicitly and tells you where everything is:
$ hh init
✓ Halfhand is set up
config created /home/me/.config/halfhand/config.toml
data dir created /home/me/.local/share/halfhand
database created /home/me/.local/share/halfhand/hh.db
blobs created /home/me/.local/share/halfhand/blobs
exports created /home/me/.local/share/halfhand/exports
● Sessions hold prompts and source code, so new directories are private (mode 0700).
Next: hh run -- <agent> e.g. hh run -- claude
It is optional. Every other command creates the data directory and
database on first use, so if you never run hh init, nothing changes for you.
What hh init adds:
- It prints every path, labelled and absolute. The paths shown are the
ones currently in effect, including any
HH_DATA_DIRor[storage] data_diroverride. - It writes a commented starter
config.tomlif you have no config file yet. Every key is listed with its purpose and its real default, and the ignore list is already filled in (**/target/**,**/.git/**,**/node_modules/**,**/.DS_Store,**/.claude/worktrees/**). Edit it, or delete lines you don't need. - It creates the data directory, blob store, exports directory and
database. Database migrations run as part of this. On Linux and macOS
every directory it creates is mode
0700, because sessions contain your prompts and source code.
Running it again
hh init is idempotent. A second run creates nothing, changes nothing, and
says so:
$ hh init
✓ Halfhand is already set up; nothing changed
config found /home/me/.config/halfhand/config.toml
...
An existing config is never overwritten. To start over from the template,
use --force. It first copies your current file to config.toml.bak (next to
config.toml, replacing any older backup), then writes the template:
hh init --force
Where things live
Halfhand uses each platform's standard directories. By default:
| Platform | Config file | Data directory |
|---|---|---|
| Linux | ~/.config/halfhand/config.toml |
~/.local/share/halfhand/ |
| macOS | ~/Library/Application Support/halfhand/config.toml |
~/Library/Application Support/halfhand/ (the same directory) |
| Windows | %APPDATA%\halfhand\config\config.toml |
%APPDATA%\halfhand\data\ (roaming profile) |
On Linux, XDG_CONFIG_HOME and XDG_DATA_HOME move these as usual. A unit
test checks this table against the code, so it stays accurate.
The data directory holds:
| Path | What it is |
|---|---|
hh.db |
The SQLite database: sessions, events, search index |
blobs/ |
Content-addressed file contents and large outputs |
exports/ |
HTML pages from hh export --html and hh replay --web |
The data directory is chosen in this order:
HH_DATA_DIRin the environment.[storage] data_dirin the config file.- The platform default from the table above.
The config file's location is always the platform default.
macOS: config and data share one directory
On macOS the config file sits inside the data directory. If you delete
~/Library/Application Support/halfhand to clear your sessions, your
config.toml goes with it. hh init warns about this whenever the two
directories are the same. To remove sessions, use hh delete (one session)
and hh gc (reclaim space) instead, or move the data elsewhere with
HH_DATA_DIR or [storage] data_dir.
Which config file is read
Halfhand looks in the config directory for:
config.toml, the canonical name;- otherwise
halfhand.toml, thenhh.toml(legacy names); - otherwise no file at all, and the built-in defaults apply.
If you only have a halfhand.toml, hh init keeps using it and does not write
a config.toml next to it, because a new config.toml would silently replace
it. Instead, it tells you which file is being read:
● reading /home/me/.config/halfhand/halfhand.toml (config.toml does not exist). Run `hh init --migrate-config` to rename it to config.toml.
Migrating halfhand.toml
hh init --migrate-config
This renames halfhand.toml (or hh.toml) to config.toml without changing
its contents. If config.toml already exists, nothing is renamed. In that case
the legacy file is being ignored, and hh init and hh doctor both point that
out.
--force refuses to run while a legacy file is the one in use. Combine the two
flags to rename the file and then replace it with the template:
hh init --migrate-config --force. Your old settings are kept in
config.toml.bak.
Checking setup with hh doctor
hh doctor adds one informational line saying whether everything hh init
creates already exists, and if not, what it would create:
● init — not run; `hh init` would create: config /home/me/.config/halfhand/config.toml, exports /home/me/.local/share/halfhand/exports
hh doctor --json adds an init object. It is purely additive: no existing
field changes, and it never affects the exit code.
"init": {
"initialized": false,
"would_create": [
{ "label": "config", "path": "/home/me/.config/halfhand/config.toml" }
]
}
Exit codes
| Code | When |
|---|---|
0 |
Setup succeeded, including "nothing changed". |
1 |
A directory, the database or the config file could not be created, read, renamed or backed up; an existing config file is malformed (fix it or use --force); or --force was used while halfhand.toml is the file in use. |
2 |
Invalid command line, such as an unknown flag. |
See Exit codes.