heddle start

A thread is an isolated line of work with its own checkout. heddle start creates or resumes the thread and materialises a checkout you can point an agent at; the thread is fully attributed and shows up in heddle thread list.

Isolated checkouts do not contain a .git directory. The binary says so in its own after-help: use Heddle commands inside them, and run Git-authority operations through Heddle from the parent Git-overlay repository. An agent that shells out to git inside a heddle start --path checkout will fail confusingly.

--workspace picks the checkout strategy: auto (the default), materialized (reflink/clonefile where the filesystem supports it), virtualized (a mounted virtual filesystem, needs a build with the mount feature), or solid (full file copies). A solid thread and a materialized thread are interchangeable from the workflow's point of view.

--hydrate symlinks the origin checkout's top-level ignored dependency directories (node_modules, .venv, target, …) into the new checkout so it builds without reinstalling. Because those directories are shared with the origin, treat hydrate as read-mostly: installing a new dependency through a hydrated link mutates the origin's copy too. That caveat lives in heddle help threads, not in the flag's own help.

--interactive-setup is the one genuinely interactive flag on this command — it opens System Settings and waits for FSKit approval on macOS, and fails before opening a GUI when there is no interactive terminal. Automation should never pass it.

Arguments

<NAME> string required

Thread name to create or resume.

Flags

--from <state>

Base state for the thread. This is how you branch the working state from an existing capture. default: HEAD

--path <path>

Filesystem path for the isolated checkout.

--workspace <mode>

Workspace mode for the thread: auto, materialized, virtualized, or solid. default: auto

--task <task>

First-class task/goal metadata for the thread.

--hydrate

Symlink the origin checkout's top-level ignored dependency directories into this isolated checkout so it is immediately buildable. The directories are shared with the origin.

--interactive-setup

Allow this invocation to open System Settings and wait briefly for FSKit approval. Requires an interactive terminal; otherwise setup fails before opening a GUI.

--parent-thread <thread> hidden

Parent thread identifier for delegated child work. Real, but absent from --help. See heddle help agent-flags.

--print-cd-path hidden

Print only the new thread's absolute checkout path to stdout and exit. Real, but absent from --help. See heddle help agent-flags.

--agent-provider <text> hidden

AI provider name for the registered agent thread. Real, but absent from --help. See heddle help agent-flags.

--agent-model <text> hidden

AI model name for the registered agent thread. Real, but absent from --help. See heddle help agent-flags.

--shared-target hidden

Redirect cargo's target/ directory to a workspace-wide shared path instead of a per-thread one. Saves gigabytes when several materialized threads coexist in a Rust workspace. Real, but absent from --help. See heddle help agent-flags.

Examples

Start an isolated thread for a task

bash$ heddle start feature/auth --path ../auth --task "wire token expiry"# the new checkout has no .git — drive it with heddle

Branch a second attempt from an existing capture

bash$ heddle start spike/cache --from hd-9c41m8bzp2hd

See also

• heddle thread
• heddle ready
• heddle land
• heddle capture