Worktree Runbook

Use a separate git worktree for agent changes so local user work remains untouched.

Create A Worktree

git fetch origin --prune
git worktree add -b codex/<short-topic> ../worktrees/hermes-ui-<short-topic> origin/main
cd ../worktrees/hermes-ui-<short-topic>

If the repository uses a fork remote, push to the remote requested by the task. Do not rewrite or reset unrelated branches.

Install

npm ci --ignore-scripts
npm rebuild node-pty

Isolated Runtime

Use per-worktree state and ports to avoid colliding with a running local app:

export PORT=18648
export HERMES_WEB_UI_HOME="$PWD/.tmp/hermes-ui"
export HERMES_WEBUI_STATE_DIR="$HERMES_WEB_UI_HOME"
export UPLOAD_DIR="$PWD/.tmp/uploads"
npm run dev:web

Do not point HERMES_WEB_UI_HOME at a user's real ~/.hermes-web-ui when a task only needs local verification.

For Electron development, first run npm run electron:setup, then launch with HERMES_ELECTRON_USER_DATA="$PWD/.tmp/chromium" npm run dev while keeping the service home overrides above. Electron selects its own loopback service port.

Browser Checks

For browser-visible changes:

npm run test:e2e

Prefer existing Playwright fixtures and mocked backend services. Add real-service requirements only when the behavior cannot be represented with mocks.

Cleanup

After a PR is pushed and no more local work is needed:

git worktree remove ../worktrees/hermes-ui-<short-topic>

Only remove the worktree you created.

1.5 KiB Raw Blame History