heddle capture

A capture saves the entire unignored working tree, hashes the content, and appends a new state to the current thread. There is no staging area and no --path filter — heddle help ignore is explicit that capture saves the full unignored worktree, and that path-scoped capture is a possible follow-up feature, not current behaviour. Exclude build junk with ignore rules before capturing; do not expect git add selectivity.

Only the two root-level ignore files are evaluated: root .gitignore and root .heddleignore, plus .heddle/info/exclude and the config's [worktree] ignore. Nested per-directory ignore files are captured as ordinary files but their patterns are not applied. A single capture that changes 500 or more paths emits a warning naming the root ignore files; the warning does not block an intentional large capture, and -f/--force skips the large-or-deletion-heavy safety preflight entirely.

The state's hd- identifier is a physical ChangeId minted fresh on every capture, so two captures with identical content get different hd- ids. The content is addressed separately by a BLAKE3 hash (shown in parentheses), and that hash is the same for identical content — but it is not something you pass to a command. See the identifier rules on Captures and states.

Attribution flags are hidden from heddle capture --help to keep everyday help terse. They are real: run heddle capture --help-agent to list them inline, or heddle help agent-flags for the topic page. Precedence, highest first: explicit flag, active thread actor, supported agent env var, harness probe, active session, user config, repo config.

Flags

--intent <text>, -m <text>

Natural language intent for this recoverable step. Accepted alias: --message.

--confidence <number>

Confidence level (0.0-1.0).

--force, -f

Allow a large or deletion-heavy capture without the safety preflight.

--help-agent hidden

Reveal the hidden agent-automation flags inline instead of capturing. Real, but absent from --help. See heddle help agent-flags.

--agent-provider <text> hidden

Override HEDDLE_AGENT_PROVIDER. Real, but absent from --help. See heddle help agent-flags.

--agent-model <text> hidden

Override HEDDLE_AGENT_MODEL. Real, but absent from --help. See heddle help agent-flags.

--agent-session <text> hidden

Override active agent session id. Real, but absent from --help. See heddle help agent-flags.

--agent-segment <text> hidden

Override active agent session segment. Real, but absent from --help. See heddle help agent-flags.

--policy <text> hidden

Override HEDDLE_AGENT_POLICY. Real, but absent from --help. See heddle help agent-flags.

--no-policy hidden

Omit policy attribution. Real, but absent from --help. See heddle help agent-flags.

--no-agent hidden

Omit agent attribution. Real, but absent from --help. See heddle help agent-flags.

--split hidden

Split selected paths into another thread instead of capturing the whole worktree. Real, but absent from --help. See heddle help agent-flags.

--into <thread> hidden

Target thread when using --split. Real, but absent from --help. See heddle help agent-flags.

--path <PATH> hidden

Repository-relative path prefix to include when using --split. Repeatable. This moves paths to another thread; it does not filter an ordinary capture. Real, but absent from --help. See heddle help agent-flags.

Examples

A typical capture

bash$ heddle capture --intent "wire datalog scope rules"Captured state hd-9a2fk3xqr7tv (b3a8e201)Confidence: 0.85

Split selected paths into another thread

bash$ heddle capture --split --into task/biscuit-authz.shim --path src/auth/jwt.rs --path src/auth/compat.rsCaptured state hd-9c41m8bzp2hd (e201b3a8)

See also

• heddle commit
• heddle status
• heddle thread
• heddle review