Project Lifecycle Scripts

Overview

Project lifecycle scripts run commands when a workspace is created or deleted, and define the dev server command for the Run button. They live in the repository or a per-machine override. Terminal scripts are different: reusable launches saved in your Paradev settings and shown in the Scripts bar.

Create .paradev/config.json in your project:

{
  "setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"],
  "teardown": ["docker-compose down"],
  "run": ["./.paradev/run.sh"]
}

How It Works

1. Create workspace → setup commands run in a terminal
2. Delete workspace → teardown commands run
3. Click the Run button → run commands execute in a dedicated pane

Setup and teardown commands run sequentially in the workspace directory.

By default, an agent launched at workspace creation starts immediately, in parallel with setup. To start it only after setup succeeds, enable Settings → Experimental → Wait for workspace setup before starting agents. The agent then runs in the same terminal as setup, and no separate setup pane is left behind.

Run Script

The run field defines commands that start your dev server or other long-running processes. Unlike setup and teardown, run commands are:

• On-demand: started by the Run button, not on workspace creation
• Restartable: stop and restart from the UI without recreating the workspace
• Dedicated pane: run in their own terminal pane, separate from your shell

Environment Variables

Examples

Node.js:

{ "setup": ["bun install", "cp \"$SUPERSET_ROOT_PATH/.env\" .env"] }

Docker:

{
  "setup": ["docker-compose up -d", "bun run db:migrate"],
  "teardown": ["docker-compose down -v"]
}

User Overrides

Override project scripts without changing the repo by placing a config.json in your home directory, mirroring the repo's absolute path:

~/.paradev/projects/<repo-path>/config.json

For a repo at /Users/me/work/app, that's ~/.paradev/projects/Users/me/work/app/config.json. The legacy location keyed by project ID (~/.paradev/projects/<project-id>/config.json) still works as a fallback.

Priority Order

For each key (setup, teardown, run), the highest-priority source that defines it wins:

1. ~/.paradev/projects/<repo-path>/config.json: user override
2. <worktree>/.paradev/config.json: workspace-specific (setup and teardown only)
3. <repo>/.paradev/config.json: project default

Levels merge per key: a key one level doesn't define falls through to the next. run resolves at the project level, so it skips the worktree layer.

Script Fallback

If no commands are configured for a key, Paradev looks for a script instead: .paradev/<key>.sh (setup.sh, teardown.sh, run.sh) in the worktree first, then the main repo. A gitignored script isn't checked out into new worktrees, so it typically exists only in the main repo.

Working Directory

Set cwd to run commands somewhere other than the workspace root. Relative paths resolve against the worktree:

{ "cwd": "apps/web", "run": ["bun dev"] }

Examples

Custom setup script:

{
  "setup": ["~/.paradev/projects/<repo-path>/setup.sh"],
  "teardown": ["~/.paradev/projects/<repo-path>/teardown.sh"]
}

Skip setup entirely:

{ "setup": [], "teardown": [] }

Local Config

Extend or override your team's committed scripts without changing the repo. Create config.local.json in the same folder as config.json, and add it to your .gitignore so it stays out of commits.

Prepend and/or append

Add steps before or after the team's scripts:

{
  "setup": {
    "before": ["echo 'running pre-setup'"],
    "after": ["./.paradev/my-post-setup.sh"]
  },
  "teardown": {
    "after": ["./.paradev/my-cleanup.sh"]
  }
}

Result: before → committed setup scripts → after. Keys you don't specify pass through unchanged.

Override entirely

Use a plain array to replace the team's scripts completely:

{
  "setup": ["./.paradev/my-custom-setup.sh"]
}

Mix and match

Override one key while extending the other:

{
  "setup": { "after": ["bun run my-extra-step"] },
  "teardown": ["my-custom-teardown.sh"]
}

Resolution order

The local config merges on top of whichever base config wins the priority order. If a config.local.json exists in both the worktree and main repo, the worktree's local config takes priority.

Force Delete

When teardown fails during workspace deletion, an error toast offers Delete Anyway and View Logs. Delete Anyway skips the failed teardown and continues cleanup. View Logs shows the failure, and you can force-delete from that dialog.

Deleting a workspace through the CLI, SDK, or MCP also runs teardown. A teardown failure there doesn't block the delete. It is reported in the response's warnings.

Tips

• Keep setup fast: it runs on every workspace creation.
• Commit .paradev/ to share it with your team.
• Use shell scripts for complex logic: "setup": ["./.paradev/setup.sh"].
• Put dev servers in run, not setup: run scripts are restartable and don't block workspace creation.