heddle init

heddle init writes the .heddle/ directory at the target path. Heddle never modifies .git/; the overlay is additive. Captures from any client (Claude Code, Cursor, Codex, anything that shells out) land in this repo.

Principal identity (the human delegator) can be set at init time via --principal-name and --principal-email. If omitted, Heddle reads them from your environment / git config later, on first capture.

On first init, Heddle offers to install harness integrations (editor hooks, agent integrations) for the host. Suppress the prompt with --no-harness-install; install a specific set with --install-harnesses; control scope with --harness-install-scope repo (default) or --harness-install-scope user.

Arguments

[path] path optional

Directory to initialise. Defaults to the current working directory.

Flags

--principal-name <name>

Principal name for attribution. Optional — falls back to env / git config later if omitted.

--principal-email <email>

Principal email for attribution. Optional — falls back to env / git config later if omitted.

--install-harnesses <names>

Comma-separated list of harness integrations to install non-interactively.

--no-harness-install

Skip the harness-integration prompt entirely.

--harness-install-scope <scope>

Where to install the harness integration. `repo` is local-to-this-repo; `user` is per-user. default: repo

--harness-install-force

Overwrite Heddle-managed integration entries when they already exist.

Examples

Adopt an existing Git repo

bash$ cd my-repo$ heddle initInitialized Heddle sidecar in /Users/me/my-repo/.heddle for Git-overlay workflows

Initialise standalone (no Git)

bash$ mkdir new-project && cd new-project$ heddle init --principal-name 'Anan' --principal-email anan@heddle.shInitialized Heddle repository in /Users/me/new-project/.heddle

See also

• heddle capture
• heddle thread
• heddle bridge git