Coding agents often work in parallel, each in its own
git worktree. Every worktree
is a full checkout of your app, so each one can deploy, run
alchemy dev, and run tests. They just need separate
stages.
Why worktrees collide
The default stages are named after your user, not your checkout.
alchemy deploy # live_sam, from every worktree
alchemy dev # dev_sam, from every worktree Two worktrees deploying live_sam are one stage. Each deploy
replaces the other's code, and a destroy in one deletes resources
the other still uses.
Name a stage after the worktree
Derive the stage from the worktree's directory name.
basename "$(git rev-parse --show-toplevel)"
# feat-x Stage names must match [a-z0-9][-_a-z0-9]*, so name worktree
directories with letters, digits, -, and _.
Deploy
Put the stage in a script so neither you nor an agent has to type it.
{
"scripts": {
"deploy": "alchemy deploy --stage live_${USER}_$(basename \"$(git rev-parse --show-toplevel)\")",
"destroy": "alchemy destroy --stage live_${USER}_$(basename \"$(git rev-parse --show-toplevel)\")"
}
} pnpm run deploy in feat-x now deploys live_sam_feat-x, and
pnpm run destroy tears down only that stage.
Dev
alchemy dev gets its own stage the same way.
{
"scripts": {
"dev": "alchemy dev --stage dev_${USER}_$(basename \"$(git rev-parse --show-toplevel)\")"
}
} Each worktree's Workers and dev servers pick a free localhost port,
so several dev sessions run side by side. Don't pin a fixed
dev.port in code that runs in more than one worktree.
Destroy a dev stage
Resources with no local emulator, and anything you pinned with
remote(),
are real cloud resources. They keep running after alchemy dev
exits. Destroy the dev stage with alchemy destroy.
{
"scripts": {
"dev:destroy": "alchemy destroy --stage dev_${USER}_$(basename \"$(git rev-parse --show-toplevel)\")"
}
} alchemy destroy defaults to the deploy stage, so always pass the
dev stage here.
Test
Test.make deploys to test_$USER by default, so tests need a
worktree stage too. How you pass it depends on your
test runner.
With @alchemy.run/test
The alchemy-test runner takes the stage as a flag.
{
"scripts": {
"test": "alchemy-test --stage test_${USER}_$(basename \"$(git rev-parse --show-toplevel)\")"
}
} pnpm test in feat-x now deploys every test stack to
test_sam_feat-x. Extra arguments still pass through, so
pnpm test test/integ.test.ts -t "serves" runs one test on the
same stage.
With bun test or Vitest
Neither runner has a stage flag. Set ALCHEMY_TEST_STAGE, which
--stage sets for you under alchemy-test.
{
"scripts": {
"test": "ALCHEMY_TEST_STAGE=test_${USER}_$(basename \"$(git rev-parse --show-toplevel)\") bun test"
}
} Swap bun test for vitest run on Vitest.
Tell your agents
Agents follow the scripts they find. Spell out the rule in
AGENTS.md (or CLAUDE.md).
## Stages
This repo is worked on from several git worktrees at once.
Never run `alchemy deploy`, `alchemy dev`, `alchemy destroy`, or the test runner directly.
Use `pnpm run deploy`, `pnpm run dev`, `pnpm run destroy`, `pnpm run dev:destroy`,
and `pnpm test`, which pick a stage named after this worktree.
Before deleting the worktree, run `pnpm run dev:destroy` and `pnpm run destroy`. Clean up before removing a worktree
A deleted worktree takes its scripts with it, not its cloud resources. Destroy its stages first.
pnpm run dev:destroy
pnpm run destroy
git worktree remove ../feat-x If the worktree is already gone, run the destroy from any checkout with the stage spelled out.
alchemy destroy --stage dev_sam_feat-x
alchemy destroy --stage live_sam_feat-x This works when the worktrees share a remote
state store. With local state, each worktree's state lives
in its own .alchemy/ directory, so destroy before you delete it.