Multi-agent worktree development environment for cloud dev with preview URLs
npm install zdevMulti-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.
- 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.
``bashRun directly
bunx 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-appOr with Convex backend
zdev create my-app --convexFlat structure (no monorepo)
zdev create my-app --convex --flat
`$3
`bash
1. Initialize your project
cd your-project
zdev init2. (Convex only) Setup Convex once if not already done
cd web # or wherever package.json is
bunx convex dev # select project, then Ctrl+C3. Start a feature
zdev start my-feature -p /path/to/project4. Work on it
cd ~/.zdev/worktrees/project-my-feature5. 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 -eUse a different package manager
pnpm installGenerate Prisma client
bunx prisma generateCopy 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: trueentryPoints:
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 developmentDirectory Structure
`
~/.zdev/
āāā config.json # Global config
āāā worktrees/ # All worktrees live here
ā āāā project-auth/
ā āāā project-billing/
āāā seeds/ # Seed data snapshots
āāā project.zip
``