Add GitHub Codespaces support with dev container and CI test

Add .devcontainer/devcontainer.json to enable Codespaces with the
existing flashx_dockerfile. Detect Codespaces in run_flashx.sh to skip
Docker build/run when the environment is already provisioned. Add a
devcontainers/ci job to the CI workflow to validate the dev container
builds correctly. Update README with browser and CLI usage instructions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: rtfisher

.devcontainer/devcontainer.json

@@ -0,0 +1,12 @@
+{
+    "name": "Flash-X Development Environment",
+    "dockerFile": "../flashx_dockerfile",
+    "build": {
+        "args": {
+            "USER_ID": "1000",
+            "GROUP_ID": "1000"
+        }
+    },
+    "remoteUser": "flashuser",
+    "postStartCommand": "echo 'Flash-X environment ready. Run cd ~/flashx/Flash-X/object && ./flashx to execute the Sedov test.'"
+}

.github/workflows/ci.yml

@@ -124,6 +124,23 @@ jobs:
       run: |
         docker run --rm flashx:test bash -c "cd /home/flashuser/flashx/Flash-X/object && ./flashx"
 
+  devcontainer-build:
+    name: Dev Container Build Test
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Build dev container
+      uses: devcontainers/ci@v0.3
+      with:
+        runCmd: |
+          echo "Dev container built successfully"
+          whoami
+          test -f /home/flashuser/flashx/Flash-X/object/flashx
+          echo "Flash-X executable found"
+
   security-scan:
     name: Security Scan
     runs-on: ubuntu-latest
@@ -150,7 +167,7 @@ jobs:
   validation-summary:
     name: Validation Summary
     runs-on: ubuntu-latest
-    needs: [lint-shell, lint-dockerfile, test-shell-script, test-dockerfile, test-integration, docker-build-and-run]
+    needs: [lint-shell, lint-dockerfile, test-shell-script, test-dockerfile, test-integration, docker-build-and-run, devcontainer-build]
     if: always()
 
     steps:
@@ -162,6 +179,7 @@ jobs:
         echo "Test Dockerfile: ${{ needs.test-dockerfile.result }}"
         echo "Integration Tests: ${{ needs.test-integration.result }}"
         echo "Docker Build and Run: ${{ needs.docker-build-and-run.result }}"
+        echo "Dev Container Build: ${{ needs.devcontainer-build.result }}"
 
         if [ "${{ needs.lint-shell.result }}" != "success" ] || \
            [ "${{ needs.lint-dockerfile.result }}" != "success" ] || \

CLAUDE.md

@@ -14,6 +14,8 @@ tests/
   test_run_flashx.bats  # Unit tests for the launcher script
   test_docker_build.bats # Dockerfile validation tests
   test_integration.bats # End-to-end integration tests
+.devcontainer/
+  devcontainer.json       # GitHub Codespaces / Dev Container config
 .github/workflows/ci.yml # CI pipeline
 ```
 
@@ -49,4 +51,5 @@ Integration tests that require a built Docker image are skipped by default (they
 - Container runs as non-root user `flashuser` with host UID/GID mapping; hostname is `flashx`
 - Volume mount: `~/flashx` on host maps to `/home/flashuser/flashx/Flash-X/desktop` in container
 - BATS tests use `@test "description" { ... }` with descriptive imperative names
-- Cross-platform support: Linux, macOS, Windows (WSL2) with `uname -s` detection
+- Cross-platform support: Linux, macOS, Windows (WSL2), and GitHub Codespaces
+- `run_flashx.sh` detects Codespaces (`CODESPACES=true`) and skips Docker build/run

README.md

@@ -58,6 +58,44 @@ This will:
 /home/flashuser/flashx/Flash-X/desktop
 ```
 
+### GitHub Codespaces (no local Docker required)
+
+You can run Flash-X entirely in the cloud using GitHub Codespaces. The repository includes a dev container configuration, so the Codespace is automatically built with all dependencies.
+
+**From the browser:**
+
+1. Navigate to [https://github.com/rtfisher/flashx_docker](https://github.com/rtfisher/flashx_docker)
+2. Click the green **Code** button, then select the **Codespaces** tab
+3. Click **Create codespace on main**
+4. Once the environment loads, open a terminal and run:
+
+```bash
+cd ~/flashx/Flash-X/object
+./flashx
+```
+
+**From the command line (GitHub CLI):**
+
+```bash
+# Create a codespace
+gh codespace create -r rtfisher/flashx_docker -b main
+
+# SSH in — pure terminal, no VS Code
+gh codespace ssh -c <codespace-name>
+
+# Once inside, the Flash-X environment is ready:
+cd ~/flashx/Flash-X/object
+./flashx
+```
+
+You can also forward ports back to your local machine if needed:
+
+```bash
+gh codespace ports forward 8000:8000 -c <codespace-name>
+```
+
+> If you run `./run_flashx.sh` inside a Codespace, it will detect the environment and drop you into the object directory directly, skipping the Docker build.
+
 ## Directory Structure
 
 ```

run_flashx.sh

@@ -21,6 +21,15 @@
 
 set -e  # Exit immediately on error
 
+# If running inside a GitHub Codespace, the environment is already set up
+# via devcontainer.json — no Docker build/run needed.
+if [ "${CODESPACES}" = "true" ]; then
+    echo "Running inside GitHub Codespaces — Docker container not needed."
+    echo "The Flash-X environment is already available."
+    cd "${HOME}/flashx/Flash-X/object"
+    exec /bin/bash
+fi
+
 # Check if Docker is running
 if ! docker info > /dev/null 2>&1; then
     echo "Docker is not running. Please start Docker and try again."