Skip to content
envctl

Agents

Coding agents that run in git worktrees are the reason envctl exists. Each agent should have a database and services nobody else is writing to, and should leave nothing behind when it finishes.

Claude Code worktree hooks

Section titled “Claude Code worktree hooks”

Claude Code fires WorktreeCreate before it creates a worktree and WorktreeRemove before it deletes one. envctl ships a script for each.

Print the configuration and merge it into the repo’s .claude/settings.json:

Terminal window
envctl hook claude
{
  "hooks": {
    "WorktreeCreate": [
      { "type": "command", "command": "envctl-worktree-create", "timeout": 600 }
    ],
    "WorktreeRemove": [
      { "type": "command", "command": "envctl-worktree-remove", "timeout": 300 }
    ]
  }
}

Both scripts must be on PATH and need jq. See Install.

What the create hook does

Section titled “What the create hook does”

Claude Code passes worktree_path, base_ref, and cwd on stdin and adopts whatever path the hook prints. The script:

  1. creates the git worktree on a worktree-<name> branch from base_ref, unless the directory exists;
  2. runs envctl up --no-wait inside it when the repo has an envctl.yaml;
  3. prints the path.

If the environment fails to start, the worktree is still returned and a message goes to stderr, so the agent can retry envctl up itself rather than losing the worktree.

What the remove hook does

Section titled “What the remove hook does”

It runs envctl down --volumes in the worktree and always exits 0, so cleanup never blocks Claude Code.

Install the skill

Section titled “Install the skill”

envctl ships a skill in the cross-agent SKILL.md format. Claude Code reads it from .claude/skills/, Codex and other agents from .agents/skills/. Install it into a repository:

Terminal window
envctl agent install
installed /path/to/repo/.claude/skills/envctl/SKILL.md
installed /path/to/repo/.agents/skills/envctl/SKILL.md

Commit those directories so every worktree and every teammate’s agent gets the skill. For a user-level install that covers every repository, use envctl agent install --global, which also writes ~/.codex/skills/envctl/.

The skill tells an agent to use envctl for lifecycle, to read envctl status --json before connecting to anything, how to address another worktree with -C, and what to do when the common errors appear. REFERENCE.md next to it carries the full command, manifest, and env file reference so the agent never has to guess.

The same files live at skills/envctl/ in the envctl repo, so npx skills add sam-bretz/envctl works for teams that manage skills that way.

What an agent should know

Section titled “What an agent should know”

Skills load on demand; a short standing note in CLAUDE.md and AGENTS.md makes sure the agent knows the environment exists before it reaches for docker compose. Print it with:

Terminal window
envctl agent snippet
## Local services (envctl)


This repository's docker-compose stack is managed by envctl. Every git
worktree has its own isolated environment. Run `envctl up` to start it
and `envctl status --json` to find service hosts and ports. Never run
`docker compose` directly on the repo's compose files and never assume a
fixed port such as localhost:5433. See the envctl skill for details.

Every command accepts --json, and status --json includes the env file lines, so an agent can read connection details in one call. See Agent automation.

Other agents and worktree managers

Section titled “Other agents and worktree managers”

Any tool that creates worktrees can call envctl -C <path> up after creation and envctl -C <path> down -v before removal. The -C flag makes envctl operate on that worktree regardless of the current directory, and the feature name is derived from that worktree’s branch.