Docs: mention managed port/DB/compose isolation as a create-hook option?

[rohansx]

worktrunk's hook docs are great — the pre-start + {{ branch | hash_port }} → .env.local example is a clean per-worktree port setup.

Running several agent worktrees at once, I hit two limits with the stateless approach: hash_port can collide across branches (there's no record of what's already taken), and I also wanted each worktree to get its own Postgres database + COMPOSE_PROJECT_NAME, so multiple docker compose ups don't clash.

I built a small single-binary tool for that layer — workz — that slots straight into a pre-start hook:

# .config/wt.toml
pre-start = "workz sync --isolated --quiet"

It allocates a collision-free port range from a small registry (not a hash), plus DB_NAME / COMPOSE_PROJECT_NAME / a DATABASE_URL derived from your existing one, merged idempotently into .env.local alongside any existing secrets.

Two questions:

1. Would you be open to a one-line "see also" in hook.md for people who need managed port/DB/compose isolation? Totally fine to keep the docs tool-agnostic — happy to just leave this here for anyone who searches.
2. Is registry-backed (vs. stateless-hash) port allocation ever something worktrunk would want natively? If so I'm glad to share notes on the aligned-range + collision-check approach.

Either way, thanks for worktrunk — the hook design is a nice thing to build on.

[worktrunk-bot]

Thanks for the thoughtful writeup — and glad the hook design has been useful to build on.

On your second question, there's direct prior art: #1130 raised almost exactly this (a registry-backed "slot number" as an alternative to the stateless hash_port, motivated by the same collision + external-resource-registration concerns). It was closed with a considered position from the maintainer — the branch↔worktree mapping being stateless is a deliberate simplicity win, so stateful allocation is something worktrunk would rather users layer on via a pre-start hook or a wt alias than build in natively. That's precisely the seam your workz fills, so this is well-aligned with how the project expects that layer to be extended (and #1130 ends with an explicit invitation to file issues if hooks/aliases turn out too limited for a case).

On the first question — a "see also" line in hook.md — that's an editorial call for a maintainer, so I'll leave it for them to weigh. Worth noting the docs stay tool-agnostic today (the collision problem is addressed inline via salting, e.g. {{ (repo ~ '-' ~ branch) | hash_port }}, per #1159), which may factor into that decision.

A maintainer will take it from here on both.

[rohansx]

Thanks — that context helps, and #1130's reasoning makes sense to me: keeping the branch↔worktree mapping stateless is a clean simplicity win, and a pre-start hook is the right seam for anyone who needs stateful allocation. So there's no ask to change worktrunk itself.

For anyone who finds this later: salted hash_port (#1159) is a good fix for port collisions specifically; what workz adds on top is the non-port isolation — a per-worktree Postgres database and COMPOSE_PROJECT_NAME so multiple docker compose ups don't clash — plus a registry so allocation is collision-proof rather than probabilistic. All opt-in via that one pre-start line.

Happy to leave the "see also" to your discretion. Thanks for the thoughtful reply!

[max-sixty]

That looks great @rohansx !

I generally want to avoid picking specific tools in the docs; becomes difficult to oversee what to recommend / I don't have a process for selecting them. One possible way: if you wanted to add an option for wt-workz or similar; and then it runs as wt workz and we could list in https://worktrunk.dev/extending/#examples (but only if you want to do that anyway, not phrasing this as some quid-pro-quo etc!)

[rohansx]

That looks great @rohansx !

I generally want to avoid picking specific tools in the docs; becomes difficult to oversee what to recommend / I don't have a process for selecting them. One possible way: if you wanted to add an option for wt-workz or similar; and then it runs as wt workz and we could list in https://worktrunk.dev/extending/#examples (but only if you want to do that anyway, not phrasing this as some quid-pro-quo etc!)

Done - added a wt-workz extension so it runs as wt workz:
https://github.com/rohansx/workz/blob/main/examples/wt-workz

Bare wt workz provisions the current worktree (collision-free port range + per-worktree Postgres DB + COMPOSE_PROJECT_NAME, merged into .env.local); any other args just forward to workz. Drop it on PATH and worktrunk picks it up git-style.

Totally your call whether it's worth a line in extending/#examples - no pressure either way. Thanks again for the pointer, and for the clean hook design.

[max-sixty]

awesome! @worktrunk-bot please add this!

[worktrunk-bot]

Done — opened #3513 adding workz to the custom-subcommand examples on the Extending page, alongside worktrunk-sync. It notes the wt-workz adapter so it dispatches as wt workz. Both links verified 200 and the skill/plugin doc mirrors are regenerated in the same PR.