Container User Experience Fixes

Date: 2025-10-28 Status: 🔴 CRITICAL - User onboarding broken Priority: P0 - Must fix before MVP launch

Problem Statement

New users logging into coditect containers face a broken experience:

❌ Wrong default directory (/workspace instead of /home/coditect)
❌ No /home/coditect/PROJECTS directory structure
❌ .claude configs in wrong location (/app/.claude instead of /home/coditect/.claude)
❌ codi2 and file-monitor may have startup issues
❌ llm CLI tools not verified to work for coditect user
❌ theia icons still not displaying properly

User Impact: "Virtually no additional configuration needed" requirement NOT met

Current State Analysis

dockerfile.combined-fixed Issues

Issue	Line	Current	Expected
Default directory	344	`WORKDIR /workspace`	`WORKDIR /home/coditect`
PROJECTS directory	-	Not created	`/home/coditect/PROJECTS` exists
.claude location	248	`/app/.claude`	`/home/coditect/.claude`
codi2 config	235, 38	Binary exists, runs blind	Needs FDB connection config
file-monitor config	236, 50	Binary exists, runs blind	Needs watch directory
llm tools verification	262-281	Installed as root	May need PATH fixes
theia icons	310-312	Warning shown	Icons should work

start-combined.sh Issues

Issue	Line	Current	Fix Needed
theia workspace	13	`/workspace`	Should be `/home/coditect/PROJECTS`
codi2 args	38	No args	Needs FDB connection string
file-monitor args	50	No args	Needs watch directory

Root Causes

1. Working Directory Mismatch

Container sets WORKDIR /workspace (Dockerfile:344)
theia opens /workspace (start-combined.sh:13)
User expects /home/coditect as home

Why this happened: Legacy from original design where /workspace was shared volume

2. Missing Directory Structure

No /home/coditect/PROJECTS created
.claude configs copied to /app/.claude (wrong location)
Ownership set correctly (chown coditect:coditect) but wrong paths

Why this happened: Incomplete migration from root user to non-root coditect user

codi2 and file-monitor start without configuration
No environment variables passed
No validation that services actually work

Why this happened: Services copied from V4 but not adapted for new container structure

4. Icon Theme Assets Missing

theia-app/plugins/ directory may not have vscode-icons.vsix
Icon theme not registered in theia config
Seti icons (built-in) not activating properly

Why this happened: Complex theia build process, icons may not be bundled correctly

Solution Design

Phase 1: Fix Directory Structure (15 min)

Dockerfile Changes

# After line 286 (after mkdir -p /workspace)
RUN mkdir -p /home/$USER_NAME/PROJECTS \
    && mkdir -p /home/$USER_NAME/.claude

# After line 258 (after COPY .claude/hooks)
# Copy .claude to user home (in addition to /app/.claude for legacy)
COPY .claude /home/$USER_NAME/.claude

# After line 292 (after chown commands)
RUN chown -R $USER_NAME:$USER_NAME \
    /home/$USER_NAME/.claude \
    /home/$USER_NAME/PROJECTS

# Change line 344
WORKDIR /home/$USER_NAME  # Changed from /workspace

start-combined.sh Changes

# Line 13 - Change theia workspace
node lib/backend/main.js /home/coditect/PROJECTS --hostname=0.0.0.0 --port=3000 &

Phase 2: Fix codi2 and file-monitor (30 min)

codi2 Configuration

Problem: codi2 needs FoundationDB connection details

# In start-combined.sh after line 34
echo "Starting CODI2 monitoring system..."
mkdir -p /app/logs/codi2

# Set FDB environment variables
export FDB_CLUSTER_FILE=/etc/foundationdb/fdb.cluster
export CODI2_LOG_LEVEL=info

if [ -f /usr/local/bin/codi2 ]; then
    # Check if FDB cluster file exists
    if [ -f "$FDB_CLUSTER_FILE" ]; then
        /usr/local/bin/codi2 --config /app/.coditect/codi2.conf > /app/logs/codi2/codi2.log 2>&1 &
        CODI2_PID=$!
        echo "CODI2 started with PID $CODI2_PID"
    else
        echo "WARNING: FDB cluster file not found at $FDB_CLUSTER_FILE - skipping CODI2"
    fi
else
    echo "WARNING: CODI2 binary not found at /usr/local/bin/codi2"
fi

file-monitor Configuration

Problem: file-monitor needs watch directory

# In start-combined.sh after line 45
echo "Starting file monitor..."
mkdir -p /app/logs/monitor

if [ -f /usr/local/bin/file-monitor ]; then
    # Watch user projects directory
    /usr/local/bin/file-monitor --watch /home/coditect/PROJECTS --log /app/logs/monitor/events.json > /app/logs/monitor/monitor.log 2>&1 &
    MONITOR_PID=$!
    echo "File monitor started with PID $MONITOR_PID"
else
    echo "WARNING: File monitor binary not found at /usr/local/bin/file-monitor"
fi

Phase 3: Fix theia Icons (45 min)

Option 1: Verify Plugin Directory

# Check if vscode-icons exists in theia-app/plugins/
ls -la theia-app/plugins/*.vsix

# If missing, download manually:
mkdir -p theia-app/plugins
cd theia-app/plugins
wget https://github.com/vscode-icons/vscode-icons/releases/download/v12.8.0/vscode-icons-12.8.0.vsix

Option 2: Register Icon Theme in theia Config

// theia-app/package.json - add to theiaPlugins section
{
  "theiaPlugins": {
    "vscode-icons-team.vscode-icons": "https://open-vsx.org/api/vscode-icons-team/vscode-icons/12.8.0/file/vscode-icons-team.vscode-icons-12.8.0.vsix"
  }
}

Option 3: Use Built-in Seti Icons

// theia-app/src-gen/frontend/index.html
// Add to head section:
<link rel="stylesheet" href="./seti/seti.css">

Phase 4: Verify llm CLI Tools (15 min)

# Add to start-combined.sh before starting services
echo "Verifying llm CLI tools..."

# Test Claude CLI
if command -v claude &> /dev/null; then
    echo "✓ Claude CLI available"
else
    echo "✗ Claude CLI not found in PATH"
fi

# Test Aider
if command -v aider &> /dev/null; then
    echo "✓ Aider available"
else
    echo "✗ Aider not found in PATH"
fi

# Test sgpt (shell-gpt)
if command -v sgpt &> /dev/null; then
    echo "✓ Shell-GPT available"
else
    echo "✗ Shell-GPT not found in PATH"
fi

# Test Grok CLI
if command -v grok &> /dev/null; then
    echo "✓ Grok CLI available"
else
    echo "✗ Grok CLI not found in PATH"
fi

# Test OpenAI CLI
if command -v openai &> /dev/null; then
    echo "✓ OpenAI CLI available"
else
    echo "✗ OpenAI CLI not found in PATH"
fi

Implementation Plan

Step 1: Update Dockerfile (5 min)

Add /home/coditect/PROJECTS creation
Add /home/coditect/.claude copy
Fix ownership of new directories
Change WORKDIR to /home/coditect

Step 2: Update start-combined.sh (10 min)

Change theia workspace to /home/coditect/PROJECTS
Add codi2 configuration with FDB checks
Add file-monitor configuration with watch directory
Add llm CLI tool verification

Step 3: Fix theia Icons (30-45 min)

Check if vscode-icons.vsix exists in theia-app/plugins/
Download if missing
Verify icon theme registration in package.json
Test in local build first

Step 4: Test in Local Docker Build (15 min)

docker build -f dockerfile.combined-fixed -t coditect-combined:test .
docker run -it --rm -p 3000:80 coditect-combined:test

# Inside container:
whoami  # Should be: coditect
pwd     # Should be: /home/coditect
ls -la .claude  # Should show agents, skills, commands
ls -la PROJECTS  # Should exist
ps aux | grep codi2  # Should be running
ps aux | grep file-monitor  # Should be running

Step 5: Deploy to GKE (Build #19) (10 min)

git add dockerfile.combined-fixed start-combined.sh
git commit -m "fix: Complete user experience fixes for coditect containers

- Set default directory to /home/coditect (not /workspace)
- Create /home/coditect/PROJECTS directory structure
- Copy .claude configs to /home/coditect/.claude
- Configure codi2 with FDB connection
- Configure file-monitor with watch directory
- Verify llm CLI tools in PATH
- Fix theia icon theme display

Fixes critical onboarding issues for MVP launch."

git push origin main
gcloud builds submit --config cloudbuild-combined.yaml

Validation Tests

Test 1: User Landing Directory

# SSH into pod
kubectl exec -it coditect-combined-0 -n coditect-app -- bash

# Expected output
pwd  # /home/coditect
ls -la  # Should show .claude/ and PROJECTS/

Test 2: .claude Configs Available

# Inside pod
ls -la /home/coditect/.claude/
# Expected: agents/, skills/, commands/, hooks/

wc -l /home/coditect/.claude/agents/*.md
# Expected: ~15 agents

Test 3: codi2 Running

ps aux | grep codi2
# Expected: Process running

cat /app/logs/codi2/codi2.log
# Expected: No errors, successful FDB connection

Test 4: file-monitor Running

ps aux | grep file-monitor
# Expected: Process running

cat /app/logs/monitor/monitor.log
# Expected: Watching /home/coditect/PROJECTS

Test 5: llm CLI Tools Work

# Inside pod as coditect user
claude --version
aider --version
sgpt --version
grok --version
openai --version

# All should return version numbers, not "command not found"

Test 6: theia Icons Display

# Open browser to https://coditect.ai/theia
# Create new file: test.js
# Expected: JavaScript icon shows next to filename
# Create new file: test.py
# Expected: Python icon shows next to filename

Success Criteria

✅ User lands in /home/coditect by default ✅ PROJECTS directory exists and writable ✅ .claude configs accessible in user home ✅ codi2 starts successfully with FDB connection ✅ file-monitor watches PROJECTS directory ✅ All llm CLI tools available in PATH ✅ theia displays file type icons correctly

Rollback Plan

If Build #19 fails:

Revert dockerfile.combined-fixed to previous version
Revert start-combined.sh to previous version
Redeploy Build #18 configuration
Debug issues locally before re-attempting

Dockerfile: dockerfile.combined-fixed:344 (WORKDIR issue)
Start Script: start-combined.sh:13 (theia workspace), start-combined.sh:38 (codi2), start-combined.sh:50 (file-monitor)
Icon Issue: dockerfile.combined-fixed:310-312 (icon verification warning)
StatefulSet: k8s/theia-statefulset.yaml (PVC mounts)

Timeline

Phase 1 (Directory Structure): 15 min
Phase 2 (codi2/file-monitor): 30 min
Phase 3 (theia Icons): 45 min
Phase 4 (llm CLI Verification): 15 min
Testing: 15 min
Deployment: 10 min

Total: ~2 hours (conservative estimate)

Notes

These fixes are CRITICAL for MVP launch
User said: "we want a complete user friendly experience with virtually no additional configuration needed"
Current state does NOT meet this requirement
All fixes can be done in parallel (separate team members)

Status: 🔧 BUILD #20 FAILED - BUILD #21 llm CLI FIX + ICON FIX READY Next Steps:

✅ Fixed llm CLI package names (Build #21)
Trigger Build #21 (llm CLI fix + icon fix combined)
Deploy and validate Build #21 (Claude configs + llm CLIs + icons)

Update Log

2025-10-28 - Build #20 Fixes Applied

All 3 critical fixes applied to codebase:

✅ Fix #1: Claude Configs (dockerfile.combined-fixed:252-269)
- Changed strategy: Copy T2 configs directly to /home/coditect/.claude/
- Merge base configs as fallback
- Removes confusing /app/.coditect/agents-t2 pattern
✅ Fix #2: llm CLI Tools (dockerfile.combined-fixed:284-298)
- Added STRICT verification that fails build if tools not found
- No more || echo soft failures
- Added PATH export to user shells (belt-and-suspenders)
✅ Fix #3: theia Icons (theia-app/package.json:125)
- Added vscode-icons to theiaPlugins section
- Uses same Open VSX pattern as other extensions
- Should load icons during theia build

Files Modified:

dockerfile.combined-fixed - 47 lines changed (252-298)
theia-app/package.json - 1 line added (125)

Next Steps:

✅ Commit changes with descriptive message (DONE)
✅ Trigger Build #20 (IN PROGRESS)
Monitor build logs for CLI verification output
Deploy to hybrid StatefulSet
Validate all 7 success criteria in production
Trigger Build #21 with icon fix (vscode-icons removed, use vs-seti)

2025-10-28 - Build #20 FAILED - npm Package Errors

ISSUE: Build #20 failed with npm 404 errors for llm CLI packages

ROOT CAUSE: Incorrect npm package names used in dockerfile.combined-fixed:272-282

ERROR OUTPUT:

npm error 404 Not Found - GET https://registry.npmjs.org/@anthropics%2fclaude
npm error 404  '@anthropics/claude@*' is not in this registry.
executor failed running [/bin/sh -c npm install -g @anthropics/claude ...]: exit code: 1

INCORRECT PACKAGE NAMES (Build #20):

RUN npm install -g \
        @anthropics/claude \              # ❌ WRONG - doesn't exist
        @anthropics/claude-code-cli \     # ❌ WRONG - doesn't exist
        @vibe-kit/grok-cli && \
    pip3 install --no-cache-dir \
        openai-cli \                      # ❌ WRONG - outdated (3 years old)
        aider-chat \
        shell-gpt \
        anthropic \
        anthropic-agent-sdk

WEB SEARCH RESEARCH FINDINGS:

Claude CLI: @anthropic-ai/claude-code (npm) - NOT @anthropics/claude
OpenAI CLI: @openai/codex (npm, v0.50.0, actively maintained) - NOT openai-cli (pip)
Gemini CLI: @google/gemini-cli (npm, v0.10.0) - Was missing entirely
Grok CLI: @vibe-kit/grok-cli (community package, no official xAI CLI) - Correct
Aider, Shell-GPT, Anthropic (Python SDKs): Already correct

2025-10-28 - Build #21 Complete Fix (llm CLIs + Icons)

COMMIT: (Pending) - "fix: Correct llm CLI package names + remove vscode-icons"

FIX #1: llm CLI Package Names (dockerfile.combined-fixed:272-282):

# CORRECTED PACKAGE NAMES (Build #21)
RUN npm install -g \
        @anthropic-ai/claude-code \       # ✅ CORRECT (command: claude)
        @openai/codex \                   # ✅ CORRECT (command: codex)
        @google/gemini-cli \              # ✅ CORRECT (command: gemini)
        @vibe-kit/grok-cli && \           # ✅ CORRECT (command: grok)
    pip3 install --no-cache-dir \
        aider-chat \                      # ✅ CORRECT (command: aider)
        shell-gpt \                       # ✅ CORRECT (command: sgpt)
        anthropic \                       # ✅ CORRECT (Python SDK)
        anthropic-agent-sdk               # ✅ CORRECT (Python SDK)

FIX #2: Verification Commands (dockerfile.combined-fixed:284-293):

# UPDATED VERIFICATION (Build #21)
RUN echo "=== Verifying llm CLI installations ===" && \
    command -v claude && claude --version || (echo "❌ Claude CLI not found" && exit 1) && \
    command -v codex && codex --version || (echo "❌ OpenAI Codex CLI not found" && exit 1) && \
    command -v gemini && gemini --version || (echo "❌ Gemini CLI not found" && exit 1) && \
    command -v aider && aider --version || (echo "❌ Aider not found" && exit 1) && \
    command -v sgpt && sgpt --version || (echo "❌ Shell-GPT not found" && exit 1) && \
    command -v grok && grok --version || (echo "❌ Grok CLI not found" && exit 1) && \
    python3 -c "import anthropic; import anthropic_agent_sdk" && \
    echo "✅ All llm CLIs verified successfully"

CHANGES FROM BUILD #20:

Changed openai --version → codex --version (@openai/codex command)
Added gemini --version verification
Removed openai-cli from pip3 install
All 6 llm CLIs now installed with correct packages

FIX #3: Icon Theme (Already committed in 77163da):

Removed duplicate vscode-icons entries (lines 125, 141)
Using theia's built-in vs-seti icons

NEXT STEPS:

Commit Dockerfile fixes (Build #21)
Trigger Build #21 (includes both llm CLI fix + icon fix)
Deploy to hybrid StatefulSet
Validate all 4 user requirements

2025-10-28 - Build #21 Icon Fix (Committed, Ready to Deploy)

ISSUE: vscode-icons extension doesn't work in theia (API limitations)

ROOT CAUSE (from web research):

theia doesn't fully support VS Code icon theming API
vscode-icons extension may not activate properly in theia
Known limitation in theia community (multiple GitHub issues)

FIX APPLIED:

✅ Removed duplicate vscode-icons entries (theia-app/package.json:125, 141)
- Line 125: vscode-icons v12.8.0 (added in Build #20)
- Line 141: vscode-icons v12.9.0 (was already there)
- Both entries removed to eliminate conflicts
✅ Kept built-in vs-seti icon theme (line 91)
- "defaultIconTheme": "vs-seti" (already correctly configured)
- vs-seti is theia's built-in icon theme
- Full VS Code compatibility without extension overhead

WHY THIS WORKS:

Built-in vs-seti icons work natively in theia
No plugin conflicts or API compatibility issues
Faster load time (no extension to download/activate)
Icons display immediately upon login

FILES MODIFIED:

theia-app/package.json - 2 lines removed (vscode-icons duplicates)

COMMIT: 77163da - "fix: Remove vscode-icons extensions, use theia built-in vs-seti icons"

NEXT STEPS:

Wait for Build #20 completion and validation
If Build #20 passes CLI validation, trigger Build #21
Deploy Build #21 to hybrid StatefulSet
Validate icons display in production

SUCCESS CRITERIA:

✅ File explorer shows file type icons (js, ts, py, rs, etc.)
✅ Search panel shows icons
✅ All UI panels display icons correctly
✅ No extension load errors in console

Problem Statement​

Current State Analysis​

dockerfile.combined-fixed Issues​

start-combined.sh Issues​

Root Causes​

1. Working Directory Mismatch​

2. Missing Directory Structure​

3. Blind Service Startup​

4. Icon Theme Assets Missing​

Solution Design​

Phase 1: Fix Directory Structure (15 min)​

Dockerfile Changes​

start-combined.sh Changes​

Phase 2: Fix codi2 and file-monitor (30 min)​

codi2 Configuration​

file-monitor Configuration​

Phase 3: Fix theia Icons (45 min)​

Option 1: Verify Plugin Directory​

Option 2: Register Icon Theme in theia Config​

Option 3: Use Built-in Seti Icons​

Phase 4: Verify llm CLI Tools (15 min)​

Implementation Plan​

Step 1: Update Dockerfile (5 min)​

Step 2: Update start-combined.sh (10 min)​

Step 3: Fix theia Icons (30-45 min)​

Step 4: Test in Local Docker Build (15 min)​

Step 5: Deploy to GKE (Build #19) (10 min)​

Validation Tests​

Test 1: User Landing Directory​

Test 2: .claude Configs Available​

Test 3: codi2 Running​

Test 4: file-monitor Running​

Test 5: llm CLI Tools Work​

Test 6: theia Icons Display​

Success Criteria​

Rollback Plan​

Related Documentation​

Timeline​

Notes​

Update Log​

2025-10-28 - Build #20 Fixes Applied​

2025-10-28 - Build #20 FAILED - npm Package Errors​

2025-10-28 - Build #21 Complete Fix (llm CLIs + Icons)​

2025-10-28 - Build #21 Icon Fix (Committed, Ready to Deploy)​