This page documents the types specific to theDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/mattpocock/sandcastle/llms.txt
Use this file to discover all available pages before exploring further.
createWorktree() API. The Worktree handle’s methods (run(), interactive(), createSandbox()) accept their own option types that are slightly different from the top-level equivalents. All types are exported from @ai-hero/sandcastle.
WorktreeBranchStrategy
createWorktree(). The head strategy is intentionally excluded because head mode means there is no worktree to create — it would be a compile-time type error to pass it here. See BranchStrategy for the full strategy shapes.
WorktreeRunOptions
Options for wt.run() — run an AFK agent in an existing worktree with a required sandbox.
Agent provider — for example
claudeCode("claude-opus-4-7").Sandbox provider. Required for AFK agent runs — unattended agents must always be sandboxed.
Inline prompt. Mutually exclusive with
promptFile.Path to a prompt file. Mutually exclusive with
prompt.Key-value map for
{{KEY}} placeholder substitution. Only valid with promptFile.Maximum iterations to run.
Substring(s) the agent emits to stop the loop early.
Idle timeout in seconds. Resets on each agent output event.
Optional display name for the run.
Logging mode:
{ type: "file", path } or { type: "stdout" }.Lifecycle hooks. See SandboxHooks.
Additional environment variables injected into the sandbox.
Resume a prior Claude Code session by ID. Incompatible with
maxIterations > 1. The session JSONL file must exist on the host.Cancel the run when aborted. If already aborted at entry, rejects immediately. Aborting mid-iteration kills the in-flight agent subprocess. The worktree is preserved on disk. The
Worktree handle remains usable for subsequent operations.WorktreeRunResult
Return value of wt.run().
Per-iteration results. Use
.length for the count.The matched completion signal, or
undefined if the loop ran to maxIterations without a match.Combined stdout output from all agent iterations.
List of commits created during the run.
The branch name the agent worked on.
Path to the log file. Only present when logging was set to
{ type: "file" }.WorktreeInteractiveOptions
Options for wt.interactive() — run a supervised interactive agent session in an existing worktree.
Agent provider.
Sandbox provider. Defaults to
noSandbox() when omitted.Inline prompt. Optional — omit to open the TUI with no initial message. Mutually exclusive with
promptFile.Path to a prompt file. Mutually exclusive with
prompt.Optional session name.
Lifecycle hooks. See SandboxHooks.
Key-value map for
{{KEY}} placeholder substitution. Only valid with promptFile.Additional environment variables injected into the sandbox.
Cancel the session when aborted. The worktree is preserved on disk. The
Worktree handle remains usable. Rejects with signal.reason.WorktreeCreateSandboxOptions
Options for wt.createSandbox() — create a long-lived sandbox backed by the existing worktree.
Sandbox provider — for example
docker().Lifecycle hooks. See SandboxHooks.
Host-relative file paths to copy into the worktree at creation time.
When you create a sandbox via
wt.createSandbox(), calling sandbox.close() tears down the container only. The worktree stays alive until you call wt.close(). This differs from top-level createSandbox(), where sandbox.close() owns both the container and the worktree.IterationResult
A single iteration’s result, available in the iterations array on any run result type.
Claude Code session ID parsed from the agent’s init line.
undefined for non-Claude agents.Absolute host path to the captured session JSONL file.
undefined when session capture is disabled or not applicable.Token usage snapshot from the last assistant message.
undefined when session capture is off or the provider does not emit usage data.IterationUsage
Token usage for a single iteration, derived from the agent’s last assistant message.
Input tokens consumed.
Tokens used to create prompt cache entries.
Tokens read from the prompt cache.
Output tokens generated.