Skip to main content
Add a .xum/init executable script to your project root to run commands when creating new workspaces. Xum falls back to a legacy .mux/init hook when .xum/init is absent. If both exist, only .xum/init runs.

​
Example

Make it executable:

​
Behavior

  • Runs once per workspace on creation
  • Streams output to the workspace UI in real-time
  • Non-blocking - workspace is immediately usable, even while hook runs
  • Exit codes preserved - failures are logged but don’t prevent workspace usage
The init script runs in the workspace directory with the workspace’s environment.

​
Environment Variables

Init hooks receive environment variables including XUM_PROJECT_PATH, XUM_RUNTIME, XUM_WORKSPACE_NAME, and more. Note for SSH workspaces: Since the project is synced to the remote machine, files exist in both locations. The init hook runs in the workspace directory ($PWD), so use relative paths to reference project files:

​
Use Cases

  • Install dependencies (npm install, bun install, etc.)
  • Run build steps
  • Generate code or configs
  • Set up databases or services
  • Warm caches

​
Output

The creation card appears after the first user message in the transcript. While setup runs, it shows a checklist of steps and checkout progress when available. Select More details to see the project path and stdout/stderr output. On success, the card collapses to Workspace created with the elapsed time. Click the header to expand the log. On failure, the card stays expanded and shows the exit code and error output.

​
Idempotency

The hook runs every time you create a workspace, even if you delete and recreate with the same name. Make your script idempotent if you’re modifying shared state.