microsoft/hve-core

Public

mirrored fromhttps://github.com/microsoft/hve-coreAvailable

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

hve-core-v2.3.5

Find a branch or tag

Branches

hve-core-v2.3.5

Clone

HTTPS

Download ZIP

hve-core/docs/getting-started/methods

docs/getting-started/methods/codespaces.md

328lines · modecode

Raw Download

Latest commit unavailable.

unknown

1	`---`
2	`title: GitHub Codespaces Installation`
3	`description: Install HVE-Core in GitHub Codespaces using postCreateCommand`
4	`author: Microsoft`
5	`ms.date: 2025-12-03`
6	`ms.topic: how-to`
7	`keywords:`
8	`- codespaces`
9	`- installation`
10	`- github copilot`
11	`- postCreateCommand`
12	`- cloud development`
13	`estimated_reading_time: 7`
14	`---`
15
16	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.
17
18	`## When to Use This Method`
19
20	`✅ Use this when:`
21
22	`* Your project runs exclusively in Codespaces`
23	`* You want automatic HVE-Core setup for all users`
24	`* You need zero-config onboarding for contributors`
25
26	`❌ Consider alternatives when:`
27
28	`* You also need local devcontainer support → [Multi-Root Workspace](multi-root.md)`
29	`* Your team needs version control → [Submodule](submodule.md)`
30	`* You're using local VS Code only → [Peer Clone](peer-clone.md)`
31
32	`## Why Other Methods Don't Work in Codespaces`
33
34	`\| Feature \| Local Devcontainer \| GitHub Codespaces \|`
35	`\|----------------------------\|---------------------\|--\|---------------------------------\|`
36	\| `${localWorkspaceFolder}` \| ✅ Resolves to host \| ❌ Not available \|
37	`\| Bind mounts to host \| ✅ Full support \| ❌ No host access \|`
38	\| Persistent storage \| Host filesystem \| `/workspaces` only \|
39	`\| User settings modification \| ✅ Via file system \| ❌ Only via Settings Sync[^1] \|`
40
41	[^1]: User-level settings require Settings Sync. Workspace/container-level settings can still be configured via `devcontainer.json` using `customizations.vscode.settings`.
42
43	`## How It Works`
44
45	`Codespaces has a specific storage model:`
46
47	```text
48	`/`
49	`├── workspaces/ # ✅ PERSISTENT - survives stops/restarts`
50	`│ ├── your-repo/ # Your cloned repository`
51	`│ └── hve-core/ # 👈 HVE-Core goes here`
52	`├── home/codespace/ # ⚠️ Semi-persistent (survives stops, not rebuilds)`
53	`└── <system-dirs>/ # ❌ Not persistent`
54	```
55
56	The `postCreateCommand` clones HVE-Core into `/workspaces/hve-core` where it persists across Codespace sessions.
57
58	`## Quick Start`
59
60	Use the `hve-core-installer` agent:
61
62	1. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
63	2. Select `hve-core-installer` from the agent picker
64	`3. Say: "Install HVE-Core for Codespaces"`
65	`4. Follow the guided setup`
66
67	`## Manual Setup`
68
69	`### Step 1: Update devcontainer.json`
70
71	`Add the clone command and VS Code settings:`
72
73	```jsonc
74	`{`
75	`"name": "My Project with HVE-Core",`
76	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
77
78	`"postCreateCommand": "[ -d /workspaces/hve-core ] \|\| git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",`
79
80	`"customizations": {`
81	`"vscode": {`
82	`"settings": {`
83	`"chat.agentFilesLocations": { "/workspaces/hve-core/.github/agents": true },`
84	`"chat.promptFilesLocations": { "/workspaces/hve-core/.github/prompts": true },`
85	`"chat.instructionsFilesLocations": { "/workspaces/hve-core/.github/instructions": true }`
86	`}`
87	`}`
88	`}`
89	`}`
90	```
91
92	`### Step 2: Commit and Push`
93
94	```bash
95	`git add .devcontainer/devcontainer.json`
96	`git commit -m "feat: add HVE-Core support for Codespaces"`
97	`git push`
98	```
99
100	`### Step 3: Create or Rebuild Codespace`
101
102	`* New Codespace: Create from the updated branch`
103	* Existing Codespace: Rebuild (`Ctrl+Shift+P` → "Codespaces: Rebuild Container")
104
105	`### Step 4: Validate Installation`
106
107	1. Open GitHub Copilot Chat (`Ctrl+Alt+I`)
108	`2. Click the agent picker dropdown`
109	`3. Verify HVE-Core agents appear (task-planner, task-researcher, prompt-builder)`
110
111	`## Complete Configuration Examples`
112
113	`### Minimal Configuration`
114
115	```jsonc
116	`{`
117	`"name": "HVE-Core Enabled",`
118	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
119
120	`"postCreateCommand": "[ -d /workspaces/hve-core ] \|\| git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",`
121
122	`"customizations": {`
123	`"vscode": {`
124	`"settings": {`
125	`"chat.agentFilesLocations": { "/workspaces/hve-core/.github/agents": true },`
126	`"chat.promptFilesLocations": { "/workspaces/hve-core/.github/prompts": true },`
127	`"chat.instructionsFilesLocations": { "/workspaces/hve-core/.github/instructions": true }`
128	`}`
129	`}`
130	`}`
131	`}`
132	```
133
134	`### Full-Featured Configuration`
135
136	```jsonc
137	`{`
138	`"name": "HVE-Core Development Environment",`
139	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
140
141	`"features": {`
142	`"ghcr.io/devcontainers/features/git:1": {},`
143	`"ghcr.io/devcontainers/features/github-cli:1": {}`
144	`},`
145
146	`"postCreateCommand": {`
147	`"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",`
148	`"verify": "test -d /workspaces/hve-core/.github/agents && echo '✅ Verified' \|\| echo '⚠️ Missing'"`
149	`},`
150
151	`"updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null \|\| echo 'Update skipped'",`
152
153	`"customizations": {`
154	`"vscode": {`
155	`"settings": {`
156	`"chat.promptFilesLocations": {`
157	`"/workspaces/hve-core/.github/prompts": true,`
158	`".github/prompts": true`
159	`},`
160	`"chat.instructionsFilesLocations": {`
161	`"/workspaces/hve-core/.github/instructions": true,`
162	`".github/instructions": true`
163	`},`
164	`"chat.agentFilesLocations": {`
165	`"/workspaces/hve-core/.github/agents": true,`
166	`".github/agents": true`
167	`}`
168	`}`
169	`}`
170	`}`
171	`}`
172	```
173
174	`### Dual-Environment (Local + Codespaces)`
175
176	`For projects needing HVE-Core in both local devcontainers and Codespaces:`
177
178	```jsonc
179	`{`
180	`"name": "HVE-Core (Local + Codespaces)",`
181	`"image": "mcr.microsoft.com/devcontainers/base:ubuntu",`
182
183	`// Clone if not already present (Codespaces path)`
184	`"postCreateCommand": "[ -d /workspaces/hve-core ] \|\| git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core",`
185
186	`// Local only: mount peer directory (silently fails in Codespaces)`
187	`"mounts": [`
188	`"source=${localWorkspaceFolder}/../hve-core,target=/workspaces/hve-core,type=bind,readonly=true,consistency=cached"`
189	`],`
190
191	`"customizations": {`
192	`"vscode": {`
193	`"settings": {`
194	`// Both paths - VS Code ignores non-existent paths`
195	`"chat.promptFilesLocations": {`
196	`"/workspaces/hve-core/.github/prompts": true,`
197	`"../hve-core/.github/prompts": true`
198	`},`
199	`"chat.instructionsFilesLocations": {`
200	`"/workspaces/hve-core/.github/instructions": true,`
201	`"../hve-core/.github/instructions": true`
202	`},`
203	`"chat.agentFilesLocations": {`
204	`"/workspaces/hve-core/.github/agents": true,`
205	`"../hve-core/.github/agents": true`
206	`}`
207	`}`
208	`}`
209	`}`
210	`}`
211	```
212
213	`## Updating HVE-Core`
214
215	`### Manual Update`
216
217	```bash
218	`cd /workspaces/hve-core`
219	`git pull`
220	```
221
222	`### Auto-Update on Codespace Start`
223
224	Add `updateContentCommand` to your devcontainer.json:
225
226	```jsonc
227	`{`
228	`"updateContentCommand": "cd /workspaces/hve-core && git pull --ff-only 2>/dev/null \|\| true"`
229	`}`
230	```
231
232	`This runs when the Codespace starts (not on every terminal open).`
233
234	`### Force Fresh Clone`
235
236	`To always get the latest version on rebuild:`
237
238	```jsonc
239	`{`
240	`"postCreateCommand": "rm -rf /workspaces/hve-core && git clone --depth 1 https://github.com/microsoft/hve-core.git /workspaces/hve-core"`
241	`}`
242	```
243
244	`Warning: This removes any local changes on every rebuild.`
245
246	`## Troubleshooting`
247
248	`### Agents Not Appearing`
249
250	`Check HVE-Core was cloned:`
251
252	```bash
253	`ls /workspaces/hve-core/.github/agents`
254	```
255
256	`Check postCreateCommand ran:`
257
258	`Look at the Codespace creation log for clone output or errors.`
259
260	`### Clone Failed During Creation`
261
262	`Network issues: Try rebuilding the Codespace.`
263
264	`GitHub rate limiting: Ensure you're authenticated:`
265
266	```bash
267	`gh auth status`
268	```
269
270	`### Settings Not Applied`
271
272	`Check devcontainer.json paths:`
273
274	Settings must use absolute paths (`/workspaces/hve-core/...`).
275
276	`Verify settings in VS Code:`
277
278	1. Open Command Palette (`Ctrl+Shift+P`)
279	`2. Type "Preferences: Open User Settings (JSON)"`
280	`3. Check if settings are present`
281
282	`### Codespace Rebuild Doesn't Update HVE-Core`
283
284	`The clone command skips if the folder exists. Force update:`
285
286	```bash
287	`cd /workspaces/hve-core`
288	`git pull`
289	```
290
291	`Or modify postCreateCommand to always pull (see Auto-Update section).`
292
293	`## Limitations`
294
295	`\| Aspect \| Status \|`
296	`\|---------------------\|-------------------------------------------\|`
297	`\| Codespaces \| ✅ Designed for this \|`
298	`\| Local devcontainers \| ⚠️ Works but consider other methods \|`
299	`\| Team sharing \| ✅ Auto-setup for all contributors \|`
300	`\| Portable paths \| ⚠️ Absolute paths only \|`
301	`\| Version pinning \| ⚠️ Modify clone command for specific tag \|`
302	`\| Offline support \| ❌ Requires network during creation \|`
303	`\| Setup complexity \| ✅ Low (just devcontainer.json) \|`
304
305	`## Version Pinning`
306
307	`To pin to a specific version:`
308
309	```jsonc
310	`{`
311	`"postCreateCommand": "[ -d /workspaces/hve-core ] \|\| git clone --depth 1 --branch v1.0.0 https://github.com/microsoft/hve-core.git /workspaces/hve-core"`
312	`}`
313	```
314
315	Replace `v1.0.0` with your desired version tag.
316
317	`## Next Steps`
318
319	`* [Your First Workflow](../first-workflow.md) - Try HVE-Core with a real task`
320	`* [Multi-Root Workspace](multi-root.md) - For dual local + Codespaces support`
321	`* [Submodule](submodule.md) - For team version control`
322
323	`---`
324
325	`<!-- markdownlint-disable MD036 -->`
326	`*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,`
327	`then carefully refined by our team of discerning human reviewers.*`
328	`<!-- markdownlint-enable MD036 -->`
329

microsoft/hve-core

Branches

Tags

Clone