Recipes

Recipes turn daft's idea — lifecycle automation per worktree — into real-world setup. Three kinds of pages here:

• Adoption recipes — introducing daft into an existing project setup, or migrating off the manual rituals you have today.
• Walkthroughs — full project shapes threading patterns end-to-end.
• Patterns — atomic problems each solved once; combine as needed.

Adoption

Recipes for introducing daft into an existing setup, or for moving off the manual rituals you have today. Start here if you're new to daft.

• Adopting from direnv — Layer daft hooks underneath an existing direnv setup — direnv keeps loading env on cd; daft adds the install/services/cleanup rituals direnv was never meant to handle.
• Adopting from mise — Layer daft hooks underneath an existing mise setup — mise keeps managing tool versions and env defaults; daft adds the install/services/cleanup rituals mise was never meant to handle.
• Layering direnv on daft — Add direnv to a daft-only project. direnv loads .env and any layout stanzas on cd; daft.yml's existing hooks remain unchanged.
• Layering mise on daft — Add mise to a daft-only project. mise pins tool versions and exports non-secret env on cd; daft.yml's existing hooks pick up the consistent toolchain.
• Migrating from a bin/setup.sh ritual — Move a project's first-time setup script into per-worktree daft hooks — same operations, no manual run, with cleanup on remove that setup.sh never had.

Walkthroughs

End-to-end recipes for full project shapes. Read the one closest to what you're building, then drop into the patterns it cites for variants.

• GitHub Actions with daft hooks — Reduce a sprawling .github/workflows/test.yml to four logical steps that consume the same daft.yml local devs use — one source of truth for setup, no "keep in sync" comment.
• Node monorepo with services — Threading toolchain-bootstrap, services-with-ports, and cleanup-on- remove into a real Node monorepo with Postgres, Redis, MinIO, and per-worktree port allocation.
• Python/uv with mise + sops secrets — Threading declarative-envs, toolchain-bootstrap, and env-vars-&-secrets into a real Python project — mise for tool versions, uv for deps, sops for secrets, layered via direnv.
• Rust binary with debug warmup — Threading toolchain-bootstrap and background-warmup into a real Rust workspace — so worktree creation returns instantly and the first cargo run is a fast incremental compile.

Patterns

Atomic problems, one recipe per problem. Combine them as your project needs.

Setup

Lifecycle stage: worktree-post-create. Get a fresh worktree from "empty checkout" to "ready to run a command."

• Background warmup — A detached prebuild job that finishes while you're still opening the editor — so the first incremental compile after your edit is fast.
• Editor integration — Per-worktree IDE settings that point at the worktree's own .venv, target/, and node_modules — so VS Code and IntelliJ pick up the right state without "Select Interpreter" rituals.
• Env vars & secrets — Per-worktree env vars and secrets — vault lookups, sops, per-job env — populated automatically on worktree create.
• Services with ports — Per-worktree compose stacks that don't collide — branch-named projects, branch-derived ports, automatic teardown.
• Toolchain bootstrap — Replace the bin/setup.sh ritual with a worktree-post-create hook that installs deps automatically — every worktree, every time.

Steady state

Patterns that span the worktree's full life — declarative env activation on cd, running the same hooks in CI for parity.

• CI parity — Run the same daft.yml in CI as you do locally — one source of truth for "how this project sets up," with rules for what to skip.
• Declarative envs — mise / asdf / nvm / pyenv as the declarative half of worktree setup — tool versions, committed env defaults, and what daft hooks add on top.

Teardown

Lifecycle stage: worktree-pre-remove. Anything the create hook brought into existence needs a way back out.

• Cleanup on remove — The symmetric mirror of worktree-post-create — tear down services, release ports, deregister state when a worktree goes away.

References

Background reading and what-not-to-do — useful alongside the patterns.

• Sharing caches across worktrees — When to share build caches between worktrees and when not — pnpm store, cargo registry, npm cache, ccache, uv cache. Per-tool answers.
• Troubleshooting recipes — Common symptoms when running daft hooks — what each error usually means and which pattern documents the fix.
• Anti-pattern: secrets in version-controlled hooks — Why committing secrets to daft.yml, exposing them in process listings, or baking them into prebuilt images is a security mistake.
• Anti-pattern: shared mutable state across worktrees — Why sharing node_modules, target/, docker volumes, or test DBs across worktrees breaks in subtle and unsubtle ways.

Pillar tags

Every recipe lists the pillar(s) it touches in its frontmatter. Filter this page with ?pillar=worktrees or ?pillar=hooks to see only recipes relevant to one pillar.

• pillars: [worktrees, hooks] — the common case (most patterns combine worktree-aware setup with hook-driven automation).
• pillars: [hooks] — hook-shaped concerns that aren't worktree-specific (CI parity).

Contributing a recipe

Spot a missing recipe? See Contributing.