GitHub Codespaces Installation

GitHub Codespaces requires a specific installation approach because traditional methods (peer directories, bind mounts) don't work in cloud environments. This method uses postCreateCommand to clone HVE Core into the persistent /workspaces directory.

When to Use This Method

✅ Use this when:

• Your project runs exclusively in Codespaces
• You want automatic HVE Core setup for all users
• You need zero-config onboarding for contributors

❌ Consider alternatives when:

• You also need local devcontainer support → Multi-Root Workspace
• Your team needs version control → Submodule
• You're using local VS Code only → Peer Clone

Why Other Methods Don't Work in Codespaces

Feature	Local Devcontainer	GitHub Codespaces
${localWorkspaceFolder}	✅ Resolves to host	❌ Not available
Bind mounts to host	✅ Full support	❌ No host access
Persistent storage	Host filesystem	/workspaces only
User settings modification	✅ Via file system	❌ Only via Settings Sync1

How It Works

Codespaces has a specific storage model:

/
├── workspaces/              # ✅ PERSISTENT - survives stops/restarts
│   ├── your-repo/           # Your cloned repository
│   └── hve-core/            # 👈 HVE Core goes here
├── home/codespace/          # ⚠️ Semi-persistent (survives stops, not rebuilds)
└── <system-dirs>/           # ❌ Not persistent

The postCreateCommand clones HVE Core into /workspaces/hve-core where it persists across Codespace sessions.

Quick Start

Install the VS Code extension for the fastest setup. For guided setup with installation method selection and MCP configuration, install the HVE Core Installer extension and ask any agent "help me customize hve-core installation". Use the manual steps below for direct configuration.

Manual Setup

Step 1: Update devcontainer.json

Add the clone command and VS Code settings:

{
  "name": "My Project with HVE Core",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  
  "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",
  
  "customizations": {
    "vscode": {
      "settings": {
        "chat.agentFilesLocations": {
          "/workspaces/hve-core/.github/agents/ado": true,
          "/workspaces/hve-core/.github/agents/data-science": true,
          "/workspaces/hve-core/.github/agents/design-thinking": true,
          "/workspaces/hve-core/.github/agents/github": true,
          "/workspaces/hve-core/.github/agents/project-planning": true,
          "/workspaces/hve-core/.github/agents/hve-core": true,
          "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
          "/workspaces/hve-core/.github/agents/security": true
        },
        "chat.promptFilesLocations": {
          "/workspaces/hve-core/.github/prompts/ado": true,
          "/workspaces/hve-core/.github/prompts/design-thinking": true,
          "/workspaces/hve-core/.github/prompts/github": true,
          "/workspaces/hve-core/.github/prompts/hve-core": true,
          "/workspaces/hve-core/.github/prompts/security": true
        },
        "chat.instructionsFilesLocations": {
          "/workspaces/hve-core/.github/instructions/ado": true,
          "/workspaces/hve-core/.github/instructions/coding-standards": true,
          "/workspaces/hve-core/.github/instructions/design-thinking": true,
          "/workspaces/hve-core/.github/instructions/github": true,
          "/workspaces/hve-core/.github/instructions/hve-core": true,
          "/workspaces/hve-core/.github/instructions/shared": true
        },
        "chat.agentSkillsLocations": {
          "/workspaces/hve-core/.github/skills": true,
          "/workspaces/hve-core/.github/skills/shared": true
        }
      }
    }
  }
}

Step 2: Commit and Push

git add .devcontainer/devcontainer.json
git commit -m "feat: add HVE Core support for Codespaces"
git push

Step 3: Create or Rebuild Codespace

• Create a new Codespace from the updated branch
• Rebuild an existing Codespace (Ctrl+Shift+P → "Codespaces: Rebuild Container")

Step 4: Validate Installation

1. Open GitHub Copilot Chat (Ctrl+Alt+I)
2. Click the agent picker dropdown
3. Verify HVE Core agents appear (task-planner, task-researcher, prompt-builder)

Complete Configuration Examples

Minimal Configuration

{
  "name": "HVE Core Enabled",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  
  "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",
  
  "customizations": {
    "vscode": {
      "settings": {
        "chat.agentFilesLocations": {
          "/workspaces/hve-core/.github/agents/ado": true,
          "/workspaces/hve-core/.github/agents/data-science": true,
          "/workspaces/hve-core/.github/agents/design-thinking": true,
          "/workspaces/hve-core/.github/agents/github": true,
          "/workspaces/hve-core/.github/agents/project-planning": true,
          "/workspaces/hve-core/.github/agents/hve-core": true,
          "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
          "/workspaces/hve-core/.github/agents/security": true
        },
        "chat.promptFilesLocations": {
          "/workspaces/hve-core/.github/prompts/ado": true,
          "/workspaces/hve-core/.github/prompts/design-thinking": true,
          "/workspaces/hve-core/.github/prompts/github": true,
          "/workspaces/hve-core/.github/prompts/hve-core": true,
          "/workspaces/hve-core/.github/prompts/security": true
        },
        "chat.instructionsFilesLocations": {
          "/workspaces/hve-core/.github/instructions/ado": true,
          "/workspaces/hve-core/.github/instructions/coding-standards": true,
          "/workspaces/hve-core/.github/instructions/design-thinking": true,
          "/workspaces/hve-core/.github/instructions/github": true,
          "/workspaces/hve-core/.github/instructions/hve-core": true,
          "/workspaces/hve-core/.github/instructions/shared": true
        },
        "chat.agentSkillsLocations": {
          "/workspaces/hve-core/.github/skills": true,
          "/workspaces/hve-core/.github/skills/shared": true
        }
      }
    }
  }
}

Full-Featured Configuration

{
  "name": "HVE Core Development Environment",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  
  "features": {
    "ghcr.io/devcontainers/features/git:1": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  
  "postCreateCommand": {
    "clone-hve-core": "if [ ! -d /workspaces/hve-core ]; then git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core && echo '✅ HVE Core cloned'; else echo '✅ HVE Core present'; fi",
    "verify": "test -d /workspaces/hve-core/.github/agents && echo '✅ Verified' || echo '⚠️ Missing'"
  },
  
  "updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null || echo 'Update skipped'",
  
  "customizations": {
    "vscode": {
      "settings": {
        "chat.promptFilesLocations": {
          "/workspaces/hve-core/.github/prompts/ado": true,
          "/workspaces/hve-core/.github/prompts/design-thinking": true,
          "/workspaces/hve-core/.github/prompts/github": true,
          "/workspaces/hve-core/.github/prompts/hve-core": true,
          "/workspaces/hve-core/.github/prompts/security": true,
          ".github/prompts": true
        },
        "chat.instructionsFilesLocations": {
          "/workspaces/hve-core/.github/instructions/ado": true,
          "/workspaces/hve-core/.github/instructions/coding-standards": true,
          "/workspaces/hve-core/.github/instructions/design-thinking": true,
          "/workspaces/hve-core/.github/instructions/github": true,
          "/workspaces/hve-core/.github/instructions/hve-core": true,
          "/workspaces/hve-core/.github/instructions/shared": true,
          ".github/instructions": true
        },
        "chat.agentFilesLocations": {
          "/workspaces/hve-core/.github/agents/ado": true,
          "/workspaces/hve-core/.github/agents/data-science": true,
          "/workspaces/hve-core/.github/agents/design-thinking": true,
          "/workspaces/hve-core/.github/agents/github": true,
          "/workspaces/hve-core/.github/agents/project-planning": true,
          "/workspaces/hve-core/.github/agents/hve-core": true,
          "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
          "/workspaces/hve-core/.github/agents/security": true,
          ".github/agents": true
        },
        "chat.agentSkillsLocations": {
          "/workspaces/hve-core/.github/skills": true,
          "/workspaces/hve-core/.github/skills/shared": true,
          ".github/skills": true
        }
      }
    }
  }
}

Dual-Environment (Local + Codespaces)

For projects needing HVE Core in both local devcontainers and Codespaces:

{
  "name": "HVE Core (Local + Codespaces)",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  
  // Clone if not already present (Codespaces path)
  "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",
  
  // Local only: mount peer directory (silently fails in Codespaces)
  "mounts": [
    "source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"
  ],
  
  "customizations": {
    "vscode": {
      "settings": {
        // Both paths - VS Code ignores non-existent paths
        "chat.promptFilesLocations": {
          "/workspaces/hve-core/.github/prompts/ado": true,
          "/workspaces/hve-core/.github/prompts/design-thinking": true,
          "/workspaces/hve-core/.github/prompts/github": true,
          "/workspaces/hve-core/.github/prompts/hve-core": true,
          "/workspaces/hve-core/.github/prompts/security": true,
          "../hve-core/.github/prompts/ado": true,
          "../hve-core/.github/prompts/design-thinking": true,
          "../hve-core/.github/prompts/github": true,
          "../hve-core/.github/prompts/hve-core": true,
          "../hve-core/.github/prompts/security": true
        },
        "chat.instructionsFilesLocations": {
          "/workspaces/hve-core/.github/instructions/ado": true,
          "/workspaces/hve-core/.github/instructions/coding-standards": true,
          "/workspaces/hve-core/.github/instructions/design-thinking": true,
          "/workspaces/hve-core/.github/instructions/github": true,
          "/workspaces/hve-core/.github/instructions/hve-core": true,
          "/workspaces/hve-core/.github/instructions/shared": true,
          "../hve-core/.github/instructions/ado": true,
          "../hve-core/.github/instructions/coding-standards": true,
          "../hve-core/.github/instructions/design-thinking": true,
          "../hve-core/.github/instructions/github": true,
          "../hve-core/.github/instructions/hve-core": true,
          "../hve-core/.github/instructions/shared": true
        },
        "chat.agentFilesLocations": {
          "/workspaces/hve-core/.github/agents/ado": true,
          "/workspaces/hve-core/.github/agents/data-science": true,
          "/workspaces/hve-core/.github/agents/design-thinking": true,
          "/workspaces/hve-core/.github/agents/github": true,
          "/workspaces/hve-core/.github/agents/project-planning": true,
          "/workspaces/hve-core/.github/agents/hve-core": true,
          "/workspaces/hve-core/.github/agents/hve-core/subagents": true,
          "/workspaces/hve-core/.github/agents/security": true,
          "../hve-core/.github/agents/ado": true,
          "../hve-core/.github/agents/data-science": true,
          "../hve-core/.github/agents/design-thinking": true,
          "../hve-core/.github/agents/github": true,
          "../hve-core/.github/agents/project-planning": true,
          "../hve-core/.github/agents/hve-core": true,
          "../hve-core/.github/agents/hve-core/subagents": true,
          "../hve-core/.github/agents/security": true
        },
        "chat.agentSkillsLocations": {
          "/workspaces/hve-core/.github/skills": true,
          "/workspaces/hve-core/.github/skills/shared": true,
          "../hve-core/.github/skills": true,
          "../hve-core/.github/skills/shared": true
        }
      }
    }
  }
}

Updating HVE Core

Manual Update

cd /workspaces/hve-core
git pull

Auto-Update on Codespace Start

Add updateContentCommand to your devcontainer.json:

{
  "updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null || true"
}

This runs when the Codespace starts (not on every terminal open).

Force Fresh Clone

To always get the latest version on rebuild:

{
  "postCreateCommand": "rm -rf /workspaces/hve-core && git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core"
}

Warning: This removes any local changes on every rebuild.

Troubleshooting

Agents Not Appearing

Check HVE Core was cloned

ls /workspaces/hve-core/.github/agents

Check postCreateCommand ran

Look at the Codespace creation log for clone output or errors.

Clone Failed During Creation

Network issues: Try rebuilding the Codespace.

GitHub rate limiting: Ensure you're authenticated:

gh auth status

Settings Not Applied

Check devcontainer.json paths

Settings must use absolute paths (/workspaces/hve-core/...).

Verify settings in VS Code

1. Open Command Palette (Ctrl+Shift+P)
2. Type "Preferences: Open User Settings (JSON)"
3. Check if settings are present

Codespace Rebuild Doesn't Update HVE Core

The clone command skips if the folder exists. Force update:

cd /workspaces/hve-core
git pull

Or modify postCreateCommand to always pull (see Auto-Update section).

Limitations

Aspect	Status
Codespaces	✅ Designed for this
Local devcontainers	⚠️ Works but consider other methods
Team sharing	✅ Auto-setup for all contributors
Portable paths	⚠️ Absolute paths only
Version pinning	⚠️ Modify clone command for specific tag
Offline support	❌ Requires network during creation
Setup complexity	✅ Low (just devcontainer.json)

Version Pinning

To pin to a specific version:

{
  "postCreateCommand": "[ -d /workspaces/hve-core ] || git clone --depth 1 --branch v1.0.0 https://github.com/microsoft/hve-core.git /workspaces/hve-core"
}

Replace v1.0.0 with your desired version tag.

Next Steps

• Your First Workflow - Try HVE Core with a real task
• Multi-Root Workspace - For dual local + Codespaces support
• Submodule - For team version control

---

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.

Footnotes

1. User-level settings require Settings Sync. Workspace/container-level settings can still be configured via devcontainer.json using customizations.vscode.settings. ↩