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.

--from bases the new thread on any state, whether a state ID, marker, HEAD, or HEAD~N, so you can branch a second attempt off an existing capture without losing the original. (There is no heddle fork; start --from is how you branch from a base.)

--workspace picks the checkout strategy: auto (let Heddle choose), materialized (disk checkout with shared extents where the filesystem supports it), virtualized (a mounted virtual filesystem, needs the mount feature), or solid (full file copies). --hydrate symlinks the origin's top-level ignored dependency directories (node_modules, .venv, target, …) into the new checkout so it's immediately buildable.

Arguments

<name> string required

Thread name to create or resume.

Flags

--from <state>

Base state for the thread. Accepts a state ID, marker, `HEAD`, `@`, or `HEAD~N`. This is how you branch the working state from a base capture. default: HEAD

--path <path>

Filesystem path for the isolated checkout.

--workspace <mode>

Checkout mode: `auto`, `materialized`, `virtualized`, or `solid`. default: auto

--task <task>

First-class task/goal metadata attached to the thread.

--hydrate

Symlink the origin checkout's top-level ignored dependency directories into the isolated checkout so it builds without reinstalling deps.

Examples

Start an isolated thread for a task

bash$ heddle start feature/auth --path ../auth --task "wire token expiry"Started isolated thread 'feature/auth' (Heddle-managed checkout, no .git directory)

Branch a second attempt from a base state (replaces `fork`)

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

See also

• heddle thread
• heddle review
• heddle context