ContextStudioWizard/HANDOVER.md

Handover — Context Studio Wizard

Last updated: 2026-03-09

Current status

The wizard runs end-to-end. The generated project (thewiztest) starts the container and opens the Electron UI. The last fix was NOT yet confirmed working by the user. The session ended before the user could test it.

What was fixed this session (newest first)

1. bin/claude — workdir fallback (UNVERIFIED — last fix, not yet tested)

File: lib/container.sh → generated bin/claude Symptom: [Server:err] claude-code is required but not found → [Server] Exited with code 1 → all agents fail to start Root cause: When Electron spawns node core/start.js, its cwd is ~/.context-studio/core. The bin/claude wrapper used --workdir "$PWD" in podman exec. That directory isn't mounted in the container → podman fails → returns non-zero → claude appears "missing". Fix: If $PWD is not under $PROJECT_DIR, fall back to $PROJECT_DIR as the container workdir. Also patched: thewiztest/bin/claude

2. Container runs as root → --dangerously-skip-permissions rejected

File: lib/container.sh → generated start.sh Symptom: --dangerously-skip-permissions cannot be used with root/sudo privileges Fix: Added --user "$(id -u):$(id -g)" and -e HOME="$HOME" to podman run Why it works: Host user elmar = uid 1000 = node user in node:22 image → permissions match Also patched: thewiztest/start.sh

3. Electron manages server startup — removed redundant headless node

File: lib/container.sh → generated start.sh Symptom: Would have caused port conflicts Fix: Removed node start.js --ui-mode=headless & from start.sh. The Electron app's server-management.js checks the lock file and spawns servers itself. Also patched: thewiztest/start.sh

4. Electron must be launched separately

File: lib/container.sh Symptom: UI never opened — servers ran but no window Root cause: node core/start.js --ui-mode=electron does NOT launch Electron. It logs "Electron app started separately" and only manages A2A servers. Fix (later superseded): Direct Electron launch via $CS_CORE/app/node_modules/.bin/electron $CS_CORE/app

What still needs verifying

1. Does the server now start without the claude-code missing error?

   • Run ./start.sh in thewiztest/
   • Watch for [12:xx:xx] ✅ All agent servers started (no Server startup failed)
   • The Electron UI should open and kai's terminal should start without root errors

2. localhost:null network error — this is downstream of (1). If servers start cleanly, the registry port gets written to the lock file and localhost:null disappears.

3. Kai can't connect to the internet — mentioned by user but not investigated. Could be:

   • Container network settings (Podman default: slirp4netns, should have internet)
   • ANTHROPIC_API_KEY not set or not passed into container
   • Proxy/VPN issue on the host network

Key architecture facts

How CS Core + Electron work together

• electron app/ starts the UI
• Electron's server-management.js checks workflow/data/ for a lock file
• If no lock file → it spawns node core/start.js --ui-mode=headless as a child process
• Child process inherits Electron's process.env including PATH (with bin/claude)
• When the requirements check runs claude --version, it finds bin/claude in PATH
• bin/claude proxies to podman exec cs-<slug> claude --version
• Container must be running BEFORE Electron is launched (start.sh handles this)

Path that must be mounted in container

Only $PROJECT_DIR is mounted (at the same absolute path). NOT:

• ~/.context-studio/core
• ~/.anthropic (mounted read-only separately)
• Any other host path

Generated files per project

• bin/claude — wrapper with hardcoded PROJECT_DIR and CONTAINER_NAME
• start.sh — starts container as $(id -u):$(id -g), exports PATH, launches Electron
• stop.sh — force-removes container
• update.sh — git pull core, npm update claude-code in container, apt upgrade

File locations

• Wizard: /home/elmar/Projects/ContextStudioWizard/
• Test project: /home/elmar/Projects/thewiztest/
• Core (read-only!): /home/elmar/.context-studio/core/
• Wizard repo remote: check git remote -v in ContextStudioWizard

What NOT to do

• Never modify ~/.context-studio/core — it is read-only
• Never commit or push to the core repo