A coding agent dropped into a consuming repo learns that repo's workflow from
its AGENTS.md (or CLAUDE.md, or whatever convention the agent reads), not
from devtrees' README. If your project uses devtrees to isolate per-worktree
stacks, paste the block below into your project's agent instructions so any
agent can drive the stack non-interactively.
The block is agent-agnostic — it's plain instructions about the devtrees CLI,
valid as AGENTS.md / CLAUDE.md content for any coding agent.
Rather than copy this by hand, run
devtrees init --agentsin your project: it writes the exact block below into yourAGENTS.md(orCLAUDE.mdif that's your convention, creatingAGENTS.mdotherwise), fenced by<!-- devtrees:start -->/<!-- devtrees:end -->markers so re-running replaces it in place. The block is generated from the same in-repo source this page quotes, so the two can't drift.
## Running the stack with devtrees
This worktree's services run under [devtrees](https://github.com/pantoninho/devtrees),
which gives every git worktree its own collision-free port block. Drive it
non-interactively — never attach the TUI:
```bash
# 1. Bring the stack up and wait for health. In a non-TTY context (an agent
# shell) `up` skips the TUI and blocks until every probed service reports
# health: ready, then exits. `--json` prints the success envelope — the
# allocated ports, per-service rows, and the injected env map — on stdout.
devtrees up --json
# 2. Load this worktree's injected ports/URLs into the environment. `devtrees
# env` prints `KEY=value` lines (use `--json` for a map); eval makes them
# available to your test command.
eval "$(devtrees env)"
# 3. Run the project's tests/build against the running stack.
<your test command> # e.g. npm test
# 4. On failure, read a service's recent logs. Without `--follow`, `logs`
# prints the buffered tail and exits — safe in a non-interactive shell.
devtrees logs <service> --tail=200
# 5. Tear the stack down when done. Re-running `down` on an already-stopped
# instance is a no-op and still exits 0.
devtrees down
```
`devtrees up` is safe to call defensively before every test run. On a stack
that is already running it hot-reloads changed config, **restarts** any
selected service that has died, then waits (up to `--wait-timeout`) for every
selected service to be healthy and exits 0 only then — immediately when all
are. It never stops anything, and never attaches the TUI.
- A bare `up` checks the namespaces the stack was booted with. `-n` checks
exactly the namespaces it names; a narrower `-n` leaves the rest running
and restarts nothing outside it.
- `-n` cannot add a namespace the running stack was not booted with: `up`
fails with `NAMESPACE_NOT_RUNNING`. Boot with it: `devtrees down && devtrees
up -n …` (the message names the exact command).
- If the stack has **namespaced shared services** (`tier: shared` with a
`namespace:`), **always pass `-n`**, every time, naming the same
namespaces you booted with. A bare `up` cannot tell that a namespace holding
only shared services was booted, so it does not select them: it neither
checks them for drift nor adds them back after `down --shared`.
- A shared port keeps its number for good, in every worktree and branch, once
any `up` has recorded it. `env --json` reports each one's origin in
`shared_ports` (`active`, `recorded`, or `predicted`: no `up` has
recorded it yet, so run `up` before relying on it).
- To recover or redefine the shared services of one namespace without
stopping the others (a drifted or wedged one, say), run
`devtrees down --shared -n <namespace>`. It stops and removes only those
services; every other shared service keeps its pid and port. It refuses
with `SHARED_IN_USE` while a running worktree still depends on one of them
(`details.dependants`). The next `up -n <namespace>` adds them back with
the current definition, on the same ports. Preview it with
`--dry-run --json`. A namespace with no running shared service is a no-op.
`SHARED_DRIFT` and `SHARED_SERVICE_DEAD` name it, with `--force`, as
`details.remedy` when the services involved are namespaced: run that
remedy as printed. When it refuses because a command is still in flight
elsewhere, its remedy is a plain retry; never add `--force` to that.
- A dead selected service (crashed, killed, or exited non-zero) is started
again, and `up` names it (`restarted` in the `--json` envelope). Several
dead services are started in `depends_on` order, without waiting between
them. If one does not become healthy, or dies again, `up` fails with
`HEALTH_TIMEOUT` naming it; if process-compose refuses to start it, with
`SERVICE_START_FAILED`. The stack is left running either way. A one-shot
that exited 0 counts as done and is not rerun.
- `up` and `down` on the same worktree take turns. An `up` that finds the
stack stopped by a concurrent `down` starts nothing and fails with
`INSTANCE_NOT_FOUND`; one that waits too long for the other fails with
`LOCK_CONTENTION`. Either way, run `devtrees up` again.
- A hot-reload whose changed service's old process never stops fails with
`CONFIG_DRIFT` (`details.reason: "timeout"`), and process-compose keeps
waiting on that process. Until it exits, `up` reloads nothing and fails
with `details.reason: "reload_pending"`, naming the service and the old
PID: a second reload would start an untracked copy. Kill the old process,
then run `devtrees up` again. `devtrees down` also works: it force-kills
that old process before it stops the stack.
- `down` never hangs on a service that will not stop (a `shutdown.command`
that leaves it running, or a process that ignores SIGTERM). After its
budget (30s plus every `shutdown.timeout_seconds`) devtrees force-kills
that service, and `down` names it (`force_killed` in the `--json`
envelope). A timed-out hot-reload is let finish first: `down` waits
for it before it stops anything, and force-kills (and names the same
way) an old process that is still stuck after that same budget. If
process-compose still does not exit, or the reload never finishes
(`details.pending_reload`), `down` fails with `DOWN_TIMEOUT`.
- `down` stops each service's whole process group. process-compose calls a
service stopped once its direct child exits, so a grandchild behind a
wrapper chain (`exec pnpm exec … -- uv run … uvicorn --reload`) that
ignores SIGTERM used to outlive it, holding its port. After process-compose
stops, devtrees gives the group's leftovers 5s (sending SIGTERM first when
process-compose did not signal the group: a `shutdown.command` or
`shutdown.parent_only`), then SIGKILLs them. Every process it signals is
named in `force_killed`. A process that left the group on purpose
(`setsid`, a detached daemon other worktrees may share) is never signalled.
- process-compose skips the `shutdown.command` of a daemon
(`is_daemon: true`) whose launch failed (`Error`, or `Completed` with a
non-zero exit), so a launch that started containers and then failed left
them running. `down` now runs those hooks itself, each bounded by its
`shutdown.timeout_seconds` or, when unset, process-compose's own 10s. If a
booted service's port still accepts connections after the stop, `down`
fails with `DOWN_INCOMPLETE` naming the holder, instead of reporting the
instance stopped; the next `down` checks the same ports again.
- A dead shared service `up` selects is restarted too, whichever worktree
runs it, and named in `shared_restarted`. A running shared service is never
touched, but `up` waits for every selected shared service to be healthy
before it succeeds, so `--wait-timeout` can apply twice (shared, then
worktree). If process-compose refuses the start, or a shared service dies
again or never becomes healthy, `up` fails with `SHARED_SERVICE_DEAD`. Its
remedy, `devtrees down --shared && devtrees up`, stops the shared instance
for every worktree.
- To cycle one service without touching the rest (a wedged dev server, say),
run `devtrees restart <service>...`. It restarts only the services it
names, in `depends_on` order, keeps their ports and the instance, and
never restarts their dependents (name those too). Each one is stopped
(waiting until it has exited, force-killing it after the same budget as
`down`, named in `force_killed`), started again, and waited on like `up`
(`--wait-timeout`) before the next. Failures read the same:
`HEALTH_TIMEOUT` leaves the stack running (`devtrees restart <service>`
tries again), `SERVICE_START_FAILED` means process-compose refused. It
refuses a shared service (`SHARED_SERVICE_REFUSED`), a service still
waiting on its dependencies (`SERVICE_PENDING`), a skipped service whose
dependency is still failed (`SERVICE_SKIPPED`: restart that dependency
with it, the command is in `details.remedy`), and the stack's last
running process (`LAST_SERVICES_RUNNING`: use `details.remedy`, a `down` +
`up`). To restart the whole stack, use that `down` + `up` too: a bare
`devtrees restart` fails `INVALID_ARGS` and prints it.
- `-n <namespace>` on `restart` acts on every isolated service of that
namespace (`devtrees restart -n app`), and can be mixed with names. Shared
services are skipped and listed in `skipped_shared`. A namespace the stack
was not booted with fails `NAMESPACE_NOT_RUNNING`, and one with no
isolated service `NO_SERVICES_SELECTED`.
### Handling failures
With `--json`, every command emits a single JSON document on **stdout** and
exits non-zero on failure: `{"error":{"code":"…","message":"…","details":{…}}}`.
Branch on `error.code`:
| Code | What it means and what to do |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| `LOCK_CONTENTION` | Another devtrees process holds a lock. Wait briefly and **retry** `up`/`down`. |
| `HEALTH_TIMEOUT` | A service never reported ready, or is still dead after `up` or `restart` restarted it (`details.dead_services`). The stack is **left running** — read `devtrees logs <service> --tail=N` to see why, then retry or follow the message (`devtrees down && devtrees up …`). |
| `NAMESPACE_NOT_RUNNING` | You asked `-n` for a namespace the running stack was not booted with. Run `details.remedy` (`devtrees down && devtrees up -n …`). |
| `SHARED_SERVICE_DEAD` | A shared service `up` could not bring back: process-compose refused to restart it, or it died again or never became healthy (`details.reason`). Read why with `devtrees logs --shared <service> --tail=N`, then run `devtrees down --shared && devtrees up` (it stops the shared instance for every worktree). |
| `SERVICE_START_FAILED` | `up` tried to restart a dead service, or `restart` a named one, and process-compose refused. `details.services` carries each one with process-compose's message; read it, then run `details.remedy` (`devtrees down && devtrees up …`). |
| `STALE_PORT_BLOCK` | Foreign listeners hold this worktree's ports. `details.collisions[]` lists `{port_name, port, pid, command, accepts_connections, port_forwarder}` (the message lists them too). Kill the orphaned holders and retry, but **never** kill one with `port_forwarder: true` (a container runtime's forwarder, such as OrbStack Helper, serving every instance: stop the container that publishes the port, `docker ps --filter publish=<port>`) or `accepts_connections: false` (usually a stale port forward). Holders that all refuse connections do not fail `up`; it warns and goes on. |
| `SHARED_DRIFT` | A shared service this `up` selects (`details.services`) runs at another revision than this worktree defines. An `up` that does not select it is unaffected. Follow the message: `devtrees down --shared && devtrees up` (it stops the shared instance for every worktree). |
| `SHARED_ACTIVATION_FAILED` | `up` could not add a namespaced shared service to the running shared instance; nothing that was running changed. `reason: timeout` → retry `devtrees up`. Otherwise **surface it to the human** with `details.remedy`. |
| `SHARED_PORT_CONFLICT` | A shared port is claimed by two names, a running shared service holds a different number than the one recorded for it, or the shared block has no free number left (`details.conflicts[].reason`). Nothing was started or recorded. `block_full` → run `details.remedy` (`devtrees prune --shared-ports`) and retry. Otherwise **surface it to the human** with `details.remedy` (`devtrees down --shared && devtrees up`, which stops the shared instance for every worktree). If the message says two map entries share a port, that is for the human to fix; never edit `shared-ports.json` or ports by hand yourself. |
| `SHARED_IN_USE` | `down --shared -n` refused: a running worktree's service, or a shared service it would keep, still depends on one it would remove, or a command is still running in a worktree (`details.dependants`). Nothing was stopped. Run `details.remedy`. While a command is in flight it is a plain retry: retry it in a moment, and never add `--force`. When `details.forceable` is true it is the `--force` rerun; stop those worktrees first (`devtrees down` in each) if they must not lose the service. |
| `SHARED_REMOVAL_FAILED` | `down --shared -n` could not finish removing the services (`details.reason`); the other shared services are untouched. **Retry** `details.remedy` once; if it fails again, **surface it to the human**. |
| `CONFIG_DRIFT` | The running config differs from `devtrees.yaml` and hot-reload failed, or an earlier reload is still pending. Branch on `details.reason`: `not_supported`/`error` → `devtrees down && devtrees up`. `timeout` → a changed service's old process won't stop: kill that process, then run `devtrees up` again to resync. Or run `devtrees down && devtrees up`: `down` force-kills that old process first and lists it in `force_killed`. `reload_pending` → that earlier reload is still waiting, so `up` reloaded nothing (another reload would start an untracked second copy): kill the old process (`details.pids`, for `details.services`), then run `devtrees up` again. Empty `details.pids` → the old process is gone and process-compose is still starting the new one: retry shortly; if it persists, follow the message's `devtrees down && devtrees up …`. |
| `SERVICE_NOT_FOUND` | You named a service that isn't in the instance. `details.valid_services` lists the real names; pick one. |
| `NO_SERVICES_SELECTED` | The selection has no services: a bare `up` starts only services with no `namespace:` and there are none, or `-n` names only namespaces with none (on `restart`, any `-n` namespace with no isolated service, in `details.selected_namespaces`). `details.namespaces` lists the namespaces; retry with one of them. |
| `INSTANCE_NOT_FOUND` | No instance is running for this worktree. Run `devtrees up` first. |
| `INSTANCE_UNRESPONSIVE` | The instance may be running but its process-compose did not answer (busy or frozen). Nothing changed. **Retry** in a moment; if it persists, follow `details.remedy`. Do not delete the socket by hand. |
| `DOWN_TIMEOUT` | `down` could not finish: process-compose was still running after devtrees force-killed the stuck services (`details.stuck_services`; empty when it is waiting on a `shutdown.command` that does not exit), or a timed-out hot-reload was still being applied, so `down` did not start the stop (`details.pending_reload`; `details.remedy` names the old process to kill by hand first, which is safe because no stop is running). Nothing was removed. **Retry** `down` once; if it fails again, **surface it to the human** with `details.remedy`, which names the process-compose pid to stop by hand, or for a pending reload the old process to kill. |
| `DOWN_INCOMPLETE` | `down` stopped process-compose, but something the instance started is still alive (`details.survivors`): a listener on a booted service's port (a container whose `shutdown.command` did not remove it, say), or a member of a service's process group that survived SIGKILL. Run `devtrees down` **once more**: with process-compose gone it runs every `shutdown.command` itself, checks the same ports again, and succeeds once they are free. If it fails the same way, **surface the survivors to the human** with `details.remedy`. Never kill a survivor with `port_forwarder: true`; stop the container that publishes its port. |
| `SHARED_SERVICE_REFUSED` | You asked `restart` for a shared service. Nothing was touched; a worktree never restarts what other worktrees share. Leave it, or restart the shared instance with `details.remedy` (`devtrees down --shared && devtrees up`). |
| `LAST_SERVICES_RUNNING` | `restart` would have to stop the last running process, and process-compose would then exit and take the whole stack down. Nothing was touched. To restart the stack, run `details.remedy` (`devtrees down && devtrees up …`). |
| `SERVICE_PENDING` | You asked `restart` for a service still waiting on its dependencies: it has not started, so nothing was touched. Wait until it starts, or restart what it waits on (`details.waiting_on`, the command is in `details.remedy`). |
| `SERVICE_SKIPPED` | You asked `restart` for a service process-compose skipped because a dependency failed, and that dependency is still failed, so a start would leave it skipped. Nothing was touched. Restart the dependency with it (`details.failed_dependencies`; the command is in `details.remedy`); if the dependency fails again, fix it first (`devtrees logs <dependency>`). |
| `PROCESS_COMPOSE_NOT_FOUND` | The `process-compose` binary is missing. **Surface this to the human** — it's an environment setup gap you can't fix. |
| `PROCESS_COMPOSE_TOO_OLD` | The installed `process-compose` is below the minimum (v1.122.0). **Surface this to the human** — they need to upgrade it. |
| `CONFIG_INVALID` / `INVALID_ARGS` | The config or your arguments are malformed. Fix the input; don't retry blindly. |
For the full error enum and the per-command subset each can emit, run
`devtrees <cmd> --help` or see [devtrees' error codes](https://github.com/pantoninho/devtrees/blob/main/docs/reference.md#error-codes).