Your project. Its containers. Your terminals. One command.

Get started · Examples · Documentation

dwork switches your development workspace. It resumes a project's existing containers, waits for healthy dependencies, and opens your commands and browser URLs. Switches stop eligible registered workspaces; locked workspaces and unregistered projects stay running. Use dwork scan to find and remember existing projects; see getting started.

Install

sh -c "$(curl -fsSL https://raw.githubusercontent.com/hayyaun/dwork/main/install.sh)"

Installs the latest main source for your user with isolated Python dependencies. No sudo or shell sourcing required. If ~/.local/bin is missing from PATH, the installer prints the line to add it.

Requires Git, Make, curl, and Python with venv: 3.10+ on Linux/WSL2 or 3.13+ on macOS. Container workspaces also need Docker and Docker Compose; terminal tasks need a supported terminal.

Inspect the installer · Installation, updates, and removal · v0.6.0 release packages · Releases and package checks

Optional tray companion

Switch saved workspaces from your desktop tray. On native Linux or macOS, include the separate tray package during installation:

TRAY=1 sh -c "$(curl -fsSL https://raw.githubusercontent.com/hayyaun/dwork/main/install.sh)"

Prerequisites and manual launch. Installation does not launch the tray or enable login startup. Native Linux/macOS users can optionally run dwork-tray --autostart enable for their next graphical login. Startup options.

On Windows/WSL2, use the portable ZIP; no separate Windows Python is needed. Windows setup · Optional sign-in startup.

Get started

Watch the 42-second demo:

dwork-preview.mp4

Find your projects, then switch to one:

cd ~/projects
dwork scan           # Find and remember workspaces
dwork list           # Show their names
dwork switch my-app  # Use a name from the list

scan finds dwork.yml workspaces and lets you select existing Compose projects, including those with compose.yml. See Describe your workspace. It saves projects without starting or stopping anything. Switching shows the plan and asks for confirmation.

For a new config, use agent setup or run dwork init inside your project. Existing Compose projects work without a dwork.yml.

dwork starts existing containers. It never creates, rebuilds, or removes them. Complete your project's initial setup and migrations first.

All commands · Scanning, groups, and locks

Describe your workspace

Current source also accepts an optional top-level name: my-app in dwork.yml as the default for new registrations and scan. Omit it to keep the existing Compose-project/directory default. Explicit dwork register NAME and saved names take precedence; this does not rename the Compose project. This field is not in v0.6.0 packages yet. See workspace naming.

For a backend with a database, put this dwork.yml beside your Compose file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/hayyaun/dwork/main/schemas/dwork.schema.json
version: 1
compose:
  enabled: true
  services: [postgres]

terminals:
  - title: Backend
    command: [make, run]
    wait_for:
      healthy: [postgres]
      timeout: 180

browsers:
  - url: http://localhost:3000
    wait_for:
      timeout: 60

Start the database → wait for healthy → open the backend → open its URL when ready. Missing containers or failed health checks block dependent tasks.

Copy a full-stack, Compose-only, or host-only example · Configuration reference

Let your coding agent set it up

Install the optional agent skill with Node.js 22.20+:

npx skills add hayyaun/dwork --skill dwork -g

Then ask your agent: "Use the dwork skill to create dwork.yml for this project." The skill inspects your existing commands and Compose services. Agent setup and usage

Explore more

• Bash and Zsh completion, including macOS Bash 3.2
• Terminal options and background tasks
• Browser selection and readiness checks
• Optional tray companion, including a portable Windows app for WSL and a replaceable icon
• Development, tests, and package build prerequisites
• Landing website source with a transparent favicon · Preview, publishing, and SEO guide; run make serve to preview at http://localhost:8000
• Social preview artwork · Project media
• All documentation