🐂 zdev

Multi-agent worktree development environment for Vite/TanStack projects.

Built for Clawdbot users who want to run multiple AI coding agents on different features simultaneously.

Supports:
- Vite / TanStack Start frontends
- Convex backend (optional — auto-detected)
- Monorepos with web/, apps/web/, etc.

Features

- Worktree Management — Isolated git worktrees per feature
- Port Allocation — Automatic port assignment, no conflicts
- Preview URLs — Public HTTPS URLs via Traefik (optional)
- Config Auto-Copy — .env.local and other files copied automatically
- Vite Support — Auto-patches allowedHosts for external access
- Convex Integration — Auto-detected; runs convex dev if present
- Monorepo Support — Auto-detects web/, frontend/, apps/web/, etc.

Installation

``bash


Run directly

bunx zdev

Or install globally

bun add -g zdev
`

Using with AI Agents

$3

Add the zdev skill to teach your agent the workflow:

`bash
npx add-skill 5hanth/zdev-skill
`

Then prompt your agent:
`
Use zdev to create a new project called my-app and start a feature branch for authentication.
`

$3

If your agent doesn't support skills, copy the SKILL.md contents into your agent's context or system prompt.

Prerequisites

$3


- Bun — curl -fsSL https://bun.sh/install | bash
- Git repository with Vite-based frontend

$3

- Convex — auto-detected if convex/ directory exists

$3

- Traefik reverse proxy with file provider
- DNS wildcard record (*.dev.yourdomain.com)

See Traefik Setup below.

Quick Start

$3

`bash


Create a new TanStack Start project

zdev create my-app

Or with Convex backend

zdev create my-app --convex

Flat structure (no monorepo)

zdev create my-app --convex --flat
`

$3

`bash


1. Initialize your project

cd your-project
zdev init

2. (Convex only) Setup Convex once if not already done

cd web # or wherever package.json is
bunx convex dev # select project, then Ctrl+C

3. Start a feature

zdev start my-feature -p /path/to/project

4. Work on it

cd ~/.zdev/worktrees/project-my-feature

5. Stop when done

zdev stop my-feature -p /path/to/project
`

Commands

$3

Create a new TanStack Start project from scratch.

`bash
zdev create my-app # Basic TanStack Start
zdev create my-app --convex # With Convex backend
zdev create my-app --flat # Flat structure (no monorepo)
`

By default creates a monorepo with web/ subdirectory. Use --flat for single-package structure.

$3

Initialize zdev for an existing project. Creates seed data from current Convex state.

`bash
zdev init # Current directory
zdev init ./my-project # Specific path
zdev init -s # Also create seed snapshot
`

$3

Start working on a feature. Creates worktree, installs deps, starts servers.

`bash
zdev start auth -p ./my-project
zdev start auth -p ./my-project --local # Skip public URL
zdev start auth -p ./my-project --port 3000 # Specific port
zdev start auth -p ./my-project --seed # Import seed data
zdev start auth --base-branch origin/develop # Different base
`

$3

Stop servers for a feature.

`bash
zdev stop auth -p ./my-project
zdev stop auth --keep # Keep worktree, just stop servers
`

$3

List all active features and their status.

`bash
zdev list
zdev list --json
`

$3

Remove a feature worktree completely (use after PR merged).

`bash
zdev clean auth -p ./my-project
zdev clean auth --force # Force even if git fails
`

$3

Manage database seed data.

`bash
zdev seed export # Export current Convex state
zdev seed import # Import into current worktree
`

$3

View and manage configuration.

`bash
zdev config --list
zdev config --set devDomain=dev.example.com
zdev config --set traefikConfigDir=/etc/traefik/dynamic
zdev config --add .env.production
zdev config --remove .env.production
`

Setup Script

zdev uses .zdev/setup.sh in your project to run setup commands when creating worktrees.

Default (generated by zdev create):
`bash
#!/bin/bash


.zdev/setup.sh - Runs after worktree creation

set -e
bun install
`

Customize it:
`bash
#!/bin/bash
set -e

Use a different package manager

pnpm install

Generate Prisma client

bunx prisma generate

Copy secrets from parent

cp ../.env.local .
`

This file is committed to git, so all team members use the same setup.

Configuration

Config stored at ~/.zdev/config.json:

| Key | Default | Description |
|-----|---------|-------------|
| devDomain | (empty) | Domain for preview URLs (e.g., dev.example.com) |
| dockerHostIp | 172.17.0.1 | How Traefik (in Docker) reaches host services |
| traefikConfigDir | /infra/traefik/dynamic | Directory where Traefik watches for route configs (see below) |
| copyPatterns | .env.local, etc. | Files to auto-copy to worktrees |

Traefik Setup for Preview URLs

> What's a "dynamic config directory"?
>
> Traefik can be configured to watch a folder for .yml files. Each file defines a route (e.g., "requests to auth.dev.example.com go to port 5173"). When you add/remove files, Traefik automatically updates its routing — no restart needed.
>
> zdev uses this to create/remove routes on-the-fly as you start/stop features.

To get public HTTPS URLs for each feature:

$3


Add a wildcard A record pointing to your server:
`
*.dev.example.com → your-server-ip
`

$3

Configure Traefik to watch a dynamic config directory:

`yaml


traefik.yml

providers:
file:
directory: /etc/traefik/dynamic # zdev writes route files here
watch: true

entryPoints:
web:
address: ":80"
websecure:
address: ":443"

certificatesResolvers:
letsencrypt:
acme:
email: you@example.com
storage: /etc/traefik/acme.json
httpChallenge:
entryPoint: web
`

$3


`bash
zdev config --set devDomain=dev.example.com
zdev config --set traefikConfigDir=/etc/traefik/dynamic
zdev config --set dockerHostIp=172.17.0.1 # or host.docker.internal on Mac
`

$3

When you run zdev start my-feature, it creates a file like /etc/traefik/dynamic/project-my-feature.yml:

`yaml
http:
routers:
project-my-feature:
rule: "Host(project-my-feature.dev.example.com)"
service: project-my-feature
entryPoints:
- websecure
tls:
certResolver: letsencrypt

services:
project-my-feature:
loadBalancer:
servers:
- url: "http://172.17.0.1:5173" # Host port from Docker's perspective
`

Traefik watches the directory and automatically picks up the new route.

Multi-Agent Workflow

1. Agent A works on auth: zdev start auth -p ./project
2. Agent B works on billing: zdev start billing -p ./project
3. Each gets isolated worktree + ports + preview URL
4. No conflicts, parallel development

Directory Structure

`
~/.zdev/
├── config.json # Global config
├── worktrees/ # All worktrees live here
│ ├── project-auth/
│ └── project-billing/
└── seeds/ # Seed data snapshots
└── project.zip
``

License

WTFPL