heddle start

Arguments

<NAME> value required

Thread name to create or resume

Flags

--from <FROM>

Base state for the thread (default: HEAD)

--path <PATH>

Filesystem path for the isolated checkout. Defaults under `.heddle/threads/`

--workspace <WORKSPACE>

Workspace mode for the thread. Omitted or `auto` still defaults the checkout under `.heddle/threads/` when `--path` is omitted values: auto · materialized · virtualized · solid

--agent-provider <AGENT_PROVIDER> hidden

AI provider name for the registered agent thread Accepted by the CLI, but absent from standard --help.

--agent-model <AGENT_MODEL> hidden

AI model name for the registered agent thread Accepted by the CLI, but absent from standard --help.

--task <TASK>

First-class task/goal metadata for the thread

--parent-thread <PARENT_THREAD> hidden

Parent thread identifier for delegated child work Accepted by the CLI, but absent from standard --help.

--automated <AUTOMATED> hidden

Internal hint that this thread was started by automation rather than a direct CLI flow values: true · false Accepted by the CLI, but absent from standard --help.

--print-cd-path <PRINT_CD_PATH> hidden

Print only the new thread's absolute checkout path to stdout and exit values: true · false Accepted by the CLI, but absent from standard --help.

--daemon <DAEMON> hidden

For `--workspace virtualized`: hand the filesystem mount off to the long-lived `heddled` daemon (default). The daemon owns the mount across CLI invocations, so the mount survives `heddle thread start` exiting. Linux-only; no-op for heavy workspaces. Pass `--no-daemon` to keep the mount in-process instead values: true · false Accepted by the CLI, but absent from standard --help. default: true

--no-daemon <NO_DAEMON> hidden

For `--workspace virtualized`: keep the filesystem mount in this CLI process instead of handing it to the `heddled` daemon. The mount unmounts when this `heddle thread start` exits — useful for one-shot inspections, debugging the in-process mount path, or environments where the daemon can't run values: true · false Accepted by the CLI, but absent from standard --help.

--interactive-setup <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 values: true · false

--shared-target <SHARED_TARGET> hidden

Redirect cargo's `target/` directory to a workspace-wide shared path (`.heddle/targets/<workspace-fingerprint>/`) instead of letting cargo create a per-thread `target/`. Saves multiples of gigabytes when several materialized threads coexist in a Rust workspace. Implemented by writing `.cargo/config.toml` inside the new thread checkout — transparent to any `cargo` invocation in that directory values: true · false Accepted by the CLI, but absent from standard --help.

--no-shared-target <NO_SHARED_TARGET> hidden

Opt out of the default shared cargo `target/` redirect for solid/materialized threads in Rust workspaces. See `--shared-target` values: true · false Accepted by the CLI, but absent from standard --help.

--hydrate <HYDRATE>

Symlink the origin checkout's top-level ignored dependency directories (`node_modules`, `.venv`, `target`, …) into this isolated checkout so it's immediately buildable — run `tsc`/`eslint`/tests without reinstalling deps from scratch values: true · false

--op-id <OP_ID> hidden

Operation id (UUID v4) for idempotent retries. See `heddle help operation-ids` Accepted by the CLI, but absent from standard --help.

Examples

checkout under .heddle/threads/

bashCopy$ heddle start feature/auth

place the checkout explicitly

bashCopy$ heddle start feature/auth --path ../feature-auth

Example

bashCopy$ heddle start fix-flake --path ../fix-flake --task 'fix CI flake'