hve-core/docs/getting-started/methods/codespaces.md at main · itsdevandy/hve-core

title

description

author

ms.date

ms.topic

keywords

estimated_reading_time

GitHub Codespaces Installation

Install HVE-Core in GitHub Codespaces using postCreateCommand

Microsoft

2025-12-03

how-to

codespaces

installation

github copilot

postCreateCommand

cloud development

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 Sync¹ |

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

Use the hve-core-installer agent:

Open GitHub Copilot Chat (Ctrl+Alt+I)
Select hve-core-installer from the agent picker
Say: "Install HVE-Core for Codespaces"
Follow the guided setup

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.modeFilesLocations": { "/workspaces/hve-core/.github/agents": true },
        "chat.promptFilesLocations": { "/workspaces/hve-core/.github/prompts": true },
        "chat.instructionsFilesLocations": { "/workspaces/hve-core/.github/instructions": 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

New Codespace: Create from the updated branch
Existing Codespace: Rebuild (Ctrl+Shift+P → "Codespaces: Rebuild Container")

Step 4: Validate Installation

Open GitHub Copilot Chat (Ctrl+Alt+I)
Click the agent picker dropdown
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.modeFilesLocations": { "/workspaces/hve-core/.github/agents": true },
        "chat.promptFilesLocations": { "/workspaces/hve-core/.github/prompts": true },
        "chat.instructionsFilesLocations": { "/workspaces/hve-core/.github/instructions": 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": true,
          ".github/prompts": true
        },
        "chat.instructionsFilesLocations": {
          "/workspaces/hve-core/.github/instructions": true,
          ".github/instructions": true
        },
        "chat.modeFilesLocations": {
          "/workspaces/hve-core/.github/agents": true,
          ".github/agents": 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": true,
          "../hve-core/.github/prompts": true
        },
        "chat.instructionsFilesLocations": {
          "/workspaces/hve-core/.github/instructions": true,
          "../hve-core/.github/instructions": true
        },
        "chat.modeFilesLocations": {
          "/workspaces/hve-core/.github/agents": true,
          "../hve-core/.github/agents": 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:

Open Command Palette (Ctrl+Shift+P)
Type "Preferences: Open User Settings (JSON)"
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.

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

When to Use This Method

Why Other Methods Don't Work in Codespaces

How It Works

Quick Start

Manual Setup

Step 1: Update devcontainer.json

Step 2: Commit and Push

Step 3: Create or Rebuild Codespace

Step 4: Validate Installation

Complete Configuration Examples

Minimal Configuration

Full-Featured Configuration

Dual-Environment (Local + Codespaces)

Updating HVE-Core

Manual Update

Auto-Update on Codespace Start

Force Fresh Clone

Troubleshooting

Agents Not Appearing

Clone Failed During Creation

Settings Not Applied

Codespace Rebuild Doesn't Update HVE-Core

Limitations

Version Pinning

Next Steps

FilesExpand file tree

codespaces.md

Latest commit

History

codespaces.md

File metadata and controls

When to Use This Method

Why Other Methods Don't Work in Codespaces

How It Works

Quick Start

Manual Setup

Step 1: Update devcontainer.json

Step 2: Commit and Push

Step 3: Create or Rebuild Codespace

Step 4: Validate Installation

Complete Configuration Examples

Minimal Configuration

Full-Featured Configuration

Dual-Environment (Local + Codespaces)

Updating HVE-Core

Manual Update

Auto-Update on Codespace Start

Force Fresh Clone

Troubleshooting

Agents Not Appearing

Clone Failed During Creation

Settings Not Applied

Codespace Rebuild Doesn't Update HVE-Core

Limitations

Version Pinning

Next Steps

Footnotes